backend-fundamentals

Backend Fundamentals — Stack-Agnostic Patterns

Universal guidance that holds for Django, FastAPI, Go (stdlib + Fiber), Rails, NestJS, Spring, and any other server-side framework. Framework-specific layering (DRF ViewSets, Pydantic Depends, Fiber middleware chain) lives in the stack-specific skill that depends_on: [backend-fundamentals].

Loaded automatically when enforce-skill.sh routes a file under backend/ that matches a stack skill.

0. Scale mindset (think before writing)

Every handler, query, and API must be written as if it will be called by 1,000 concurrent users on a 50M-row table. Before writing:

• How many rows does this touch? Unknown → run EXPLAIN ANALYZE or ask.
• How many callers at once? Single-user admin page vs. public endpoint changes everything.
• Where's the bottleneck? DB index miss · network hop · CPU work.
• What's the latency budget? Default P99 < 500 ms; surface the number in the PR description.
• What happens if step 3 of 5 fails? Transactions · idempotency key · compensating action.

Code that works on 10 rows but collapses on 10 M is a production incident waiting for traffic. Correct answer to "will this scale?" is a number, not "yes".

1. Service / selector split

Business logic lives in services (write path — mutates state, encapsulates a transaction). Read-only DB queries live in selectors (pure functions, cached when possible). Controllers / views / handlers only:

1. Parse and validate the request.
2. Call a service or selector.
3. Shape the response.

No ORM calls in controllers. No business rules in serializers. No DB writes in selectors. This split makes unit testing trivial (mock the service boundary) and keeps transaction boundaries visible.

2. Standard response envelope

Every handler returns one of:

{ "ok": true,  "data":  <T> }
{ "ok": false, "error": { "code": "<UPPER_SNAKE>", "message": "<human>", "retryable": true|false } }

Error codes come from a project-level registry (list every code in one file, e.g. backend/errors.py or docs/api-contracts/error-codes.md). Never invent codes on the fly — if a new case doesn't fit an existing code, add the new code to the registry first, then reference it.