Non-Functional Requirements — Custom Ecommerce Backend API for a Clothing Brand

Overview

Non-functional requirements: the qualities that decide whether a commerce backend survives real traffic, real attackers, and real audits. Where a target isn't formally defined, it's marked TBD rather than invented.

Security

Quality	Implementation
Transport & headers	helmet defaults; secure cookies in production
Session security	Peppered `SHA-256(token + SESSION_SECRET)` hashes; `httpOnly` + `SameSite=Lax` cookies; 14-day idle timeout; per-device metadata + revocation (single + revoke-others)
CSRF	`csrf-csrf` double-submit bound to the `session` cookie; anonymous skipped; fail-closed in production (`ENABLE_CSRF` boot guard, server refuses to boot when disabled)
Brute force	Per-email lockout (10 attempts / 15 min); dedicated rate limiters on login, register, email verification/change, phone change, password reset
Secrets	Boot-time zod validation of every env var (including `SESSION_SECRET≥16`, `TRUST_PROXY`, `IMAGEKIT_*`) — hard exit on missing/invalid configuration
Input safety	zod on body/query/params of all 77 endpoints (including `public_id` prefix patterns and report `period
Privacy	Sensitive keys redacted from logs and `audit_logs`; single-use tokens (verification/OTP) are plaintext in logs only as redact-safe prefixes
Transport	`helmet` defaults; `Secure` cookies in production; `TRUST_PROXY` hop count for correct IP behind the platform edge

Reliability & Data Integrity

Transactional checkout with per-user pg_advisory_xact_lock — no partial orders; coupon quota restored atomically on pre-fulfillment cancel.
Guarded writes everywhere — conditional UPDATEs (available >= qty, usage_count limits) and affected-row assertions convert silent failures into explicit 409/404 instead of 500.
Graceful shutdown — SIGTERM/SIGINT drains connections (10 s cap), flushes pino logs within 1 s.
Race-condition regression tests: registerRace/productSlugRace/categoryAssignRace/cart.race/cartConcurrency, last-admin protection, slug collisions — each asserts exactly one winner and clean degradation for the loser.

Testability

1,132 test cases across 78 files (as of reports epic): three suites — unit, integration (real PostgreSQL), and e2e HTTP via supertest (fileParallelism: false because suites share one schema) — including 21 report integration tests for 401|403|400 and application/pdf streaming (Content-Disposition, X-Report-Currency, %PDF-).
Test-database self-protection: the suite refuses to run against a database whose name doesn't contain "test"; rate limiters stay active in e2e, global limiter is intentionally skipped in test.
CI (pull_request → main) boots a PostgreSQL 16 service, provisions the schema, writes .env.test from repository secrets (SESSION_SECRET, RESEND_*, IMAGEKIT_*), runs typecheck (app + tests separately), build, migration deploy, boot smoke (/health), then the full suite.

Observability

Aspect	Detail
Logging	`pino` with `x-request-id` correlation, method/url/status/duration + user/IP/UA + stashed error; query strings redacted to pathname; `silent` in `test`, size-rotated NDJSON in production
Audit trail	Append-only `audit_logs` — every authenticated `POST/PUT/PATCH/DELETE` on `/admin/*` plus business events (order placed, coupon redeemed); `request_body`/`previous_values`/`changes` + IP/UA
Health checks	`/health` liveness (static `{ status: ok }`) + `/health/ready` with a 2 s `SELECT 1` probe (200 or 503) — both outside the rate limiter

Performance

Deliberate indexing including post-launch composite index migrations driven by query analysis.
Offset pagination capped at 100 items. Cursor pagination: not implemented — acceptable at current scale, noted as future work.

Targets

Latency/throughput SLOs are TBD — requires load testing. The architecture (stateless app, indexed queries, connection pooling via Prisma driver adapter) is built to support them.

Maintainability

Uniform five-layer module structure across fifteen domains — any developer can navigate any feature.
Zero TODO/FIXME comments in src/ — technical debt lives in an 87-item numbered task ledger referenced from code comments ((T-043)), making debt searchable and prioritizable.
CI enforces typecheck (app + tests separately), build, migration deploy, boot smoke, full suite on every push.

Known Limitations

Area	Gap	Status
Payments	Mock gateway only	Designed, tracked (Paymob tasks T-081–T-087)
SMS	Logging stub that `pino`-logs instead of sending	Tracked (T-009)
Rate limiting	In-memory per instance — effective limits multiply behind N instances	Mitigated via single instance or shared Redis store; documented in `docs/DEPLOYMENT.md`
OpenAPI	77-path OpenAPI 3.1 spec mirrors `docs/api/**` but is not linted in CI vs markdown contracts	Tracked (T-011/T-054)
Coverage	`coverage-v8` tooling present, thresholds not enforced	Tracked

Result

Not "production-ready" as a slogan — production-ready as a checklist: concurrency proven by tests, security layered by default, debt tracked instead of hidden.