building-backends

Building Backends

Prerequisites

Load architecting-changes and api-design before this skill. They provide the architecture decision framework, boundaries, pattern awareness, and API design principles. This skill adds backend-specific heuristics: transaction ownership, auth context patterns, worker rules, and common backend mistakes.

Also load engineering-principles (via myai bootstrap).

Core Rules

• Routes and workers decode input, call one core operation, then map the result outward. They are thin adapters, not orchestration layers.
• Convert auth/session/request state immediately at the edge into framework-free typed inputs and actor/principal values. Framework auth objects never enter domain code.
• Expected failures stay as Result types through core layers. HTTP status mapping (or equivalent transport error encoding) happens at the transport boundary only. Errors are domain values, not transport codes.
• Exceptions are bugs or infrastructure escapes. Catch them at the global error boundary and in wrappers around actions that may throw.

Persistence and Transactions

• A use-case/handler/service owns the transaction boundary. The use-case/handler/service decides when to commit or roll back.
• Repositories are optional, not mandatory. Use them when they express a real persistence boundary, not because the pattern exists. For simple CRUD through an ORM, the ORM may be the repository.
• Routes must not open, commit, and orchestrate business transactions inline. Transaction management belongs in the use-case/handler/service layer.
• Repositories must not silently commit their own work for multi-step flows. A repository that auto-commits inside a multi-step operation breaks atomicity.

Workers and Background Work

• Workers are another adapter calling the same core services as HTTP or CLI. Do not duplicate business logic in worker handlers.
• Important background work should have an explicit job payload and handler. Make the job contract visible, not buried in closure state.
• Do not hide important work inside fire-and-forget tasks started from request handlers. If the work matters, it deserves a job, not a dangling promise.
• If work needs retries, durability, or traceability, treat it as a real backend workflow with explicit state, not a convenience callback.

Auth and Operation Context

• Keep framework auth/session objects at the edge. Pass a typed actor/principal into core operations.
• Important write operations should expose execution context clearly: actor, request ID, idempotency key, and mode when needed. This makes operations inspectable and auditable.
• Prefer typed mode values over a naked boolean flag (e.g. dry_run: bool is bad) when behavior meaningfully changes. A mode enum makes the intent explicit and prevents boolean confusion.

Common Mistakes

• business logic and DB commits inline in routes
• request DTOs or ORM rows used as domain models
• framework request/auth/session objects leaking into core code
• generic repository layers everywhere (use only at real persistence boundaries)
• separate worker logic duplicating route logic
• important writes without idempotency, dry-run, or traceability where they matter
• CLI or admin scripts bypassing the real core services

Ecosystem Examples

Python

• FastAPI is the default boring HTTP adapter for most service APIs.
• Django is justified when backend complexity, admin, auth/session, and CRUD surface are obviously large from day 1.
• SQLAlchemy 2 + Alembic is the default relational stack when the service owns its DB.
• Use pydantic DTOs at the FastAPI HTTP edge — convert immediately to framework-basic types (msgspec.Struct for config types, dataclass for domain models).
• Use Result[T, E] (rusty-results) for expected failures through core layers. Map to HTTP status codes at the transport boundary only.
• httpx wrappers own outbound HTTP boundaries.
• Add Redis, queues, and extra infrastructure only when the product actually needs them.

TypeScript / Node

• NestJS is the default boring backend framework for most service APIs. Its module system, guards, interceptors, and pipes map well to the layered architecture.
• Hono is alternative HTTP layer for edge environments where runtime is limited.
• Express + manual middleware is justified for very thin-edge builds or when framework weight is actively undesirable.
• Prisma or Drizzle for relational persistence. Keep ORM models at the infrastructure layer — map to plain domain types at the service boundary.
• Use appropriate runtime schema validator (e.g., Zod, Valibot) for request/response validation at the HTTP edge. Convert validated transport DTOs immediately into plain domain types. Transport schemas describe the wire format; domain models are not transport schemas.
• Use Result<T, E> (neverthrow, effect, or custom Either) for expected failures through core layers. Map to HTTP status codes in exception filters or error middleware.
• fetch / undici wrappers own outbound HTTP boundaries.
• Add BullMQ, Redis, and extra infrastructure only when needed.

Handoff

• Use setting-up-backends for new backend repo bootstrap and initial scaffolding.
• Use setting-up-projects for general project shape decisions.
• Use api-design for stable API contract and protocol design.
• Use security-and-hardening for auth, secrets, and boundary hardening.

Related myai Skills

• architecting-changes — Parent skill. Architecture decision framework, boundaries, pattern awareness.
• api-design — Parent skill. Stable API and protocol design.
• engineering-principles — Foundation. Language-agnostic philosophy.
• setting-up-backends — Backend repo bootstrap and scaffolding.
• setting-up-projects — General project shape and layout.
• security-and-hardening — Auth, secrets, rate limiting.