API Service Scaffold

api-service-scaffold

Scaffold a new backend service that is shaped correctly from commit one: clear layers, one error model, validation at the edge, config from the environment, and a health/readiness surface an orchestrator can probe. The goal is a skeleton a team can build on for years, not a demo that has to be re-architected the first time it meets production.

When to use

• Standing up a brand-new service.
• Adding a new bounded context / module to an existing monorepo (reuse the repo's conventions; this skill fills the gaps).
• Rescuing a service that grew without layers — apply the target structure below incrementally.

Non-negotiables (hold these on every scaffold)

• One error model. Every failure leaves the domain as a typed error and is mapped to a transport status in exactly one place (the handler/middleware boundary). No throw new Error("bad") escaping to the client.
• Validation at the edge. Untrusted input is parsed into a typed value object at the boundary; the core never sees a raw request body.
• Config is injected, never read deep in the tree. One config module reads the environment once, validates it, and is passed down. No process.env.X / os.environ[...] in business logic.
• No I/O in the domain layer. Handlers orchestrate; services hold logic; repositories own I/O. The domain is testable without a network or a database.
• Health ≠ readiness. /healthz = "process is up"; /readyz = "dependencies reachable". Orchestrators need both distinct.

Target layout

src/
  config/        # env parsing + validation, typed config object
  http/          # transport: routes, request/response mapping, middleware
  domain/        # entities, value objects, domain errors — no I/O
  services/      # use-cases; orchestrate domain + repositories
  repositories/  # data access; the ONLY layer that talks to DB/queue/HTTP
  observability/ # logger, metrics, tracing setup (see backend-observability)
  app.ts|main.py # composition root: build config → wire deps → start server
test/
  smoke/         # one test that boots the app and hits /healthz + one real route

Dependencies point inward only: http → services → domain, services → repositories → domain. domain imports nothing outward. If an import arrow points the wrong way, the layering is broken — fix it before moving on.

Procedure

1. Read the repo first. If this is a monorepo, match its lint config, package manager, test runner, and error conventions. Do not introduce a second way of doing something the repo already does.
2. Config module. Parse the environment once into a validated, typed object. Fail fast at boot on a missing/malformed required var — a service that starts with bad config and 500s on first request is worse than one that refuses to start.
3. Error model. Define a small hierarchy of domain errors (NotFoundError, ValidationError, ConflictError, UnauthorizedError, …), each carrying a stable machine-readable code. Add one mapper at the transport boundary: domain error → status + JSON body { code, message, details? }. Never leak stack traces or internal messages to clients.
4. Boundary validation. Pick one schema library (zod / pydantic / io-ts) and parse every inbound body, query, and param into a typed value at the handler. On failure, raise ValidationError → 422 with field-level details.
5. One vertical slice. Wire a single real route end to end (handler → service → repository, with an in-memory or real repo) so the skeleton is runnable, not just directories.
6. Health surface. /healthz returns 200 unconditionally once the event loop is live. /readyz pings each critical dependency with a short timeout and returns 200 only if all are reachable; 503 otherwise, with a per-dependency status body.
7. Smoke test. One test boots the app, asserts /healthz is 200 and the vertical-slice route returns its happy-path shape. This is the gate that keeps the skeleton alive as it grows.
8. Graceful shutdown. On SIGTERM: stop accepting new connections, drain in-flight requests with a bounded deadline, close DB/queue pools, then exit. Orchestrators send SIGTERM before SIGKILL — use the window.

Error → status mapping (the one table)

Node / TypeScript recipe

• Runtime web layer: Fastify (schema-first, fast) or Express if the repo already uses it.
• Validation: zod, inferred types shared between transport and services.
• Config: a single loadConfig() that zod-parses process.env and is called once in the composition root.
• Test: vitest or jest; the smoke test uses the framework's inject/supertest to hit routes without opening a port.

Python / FastAPI recipe

• FastAPI + pydantic v2 models as the boundary schema (validation is built in).
• Config: pydantic-settings BaseSettings subclass, instantiated once.
• Dependency wiring via FastAPI Depends; keep use-cases as plain functions/classes so they're unit-testable without the framework.
• Test: pytest + httpx.AsyncClient against the ASGI app in-process.

Definition of done

• lint and typecheck clean.
• test/smoke passes: app boots, /healthz 200, one real route returns its documented shape.
• No process.env / os.environ outside config/; no raw Error reaching a client; no I/O import inside domain/.
• README documents required env vars and the run/test commands.