Status: Accepted
Context#
The API needs a high-throughput Node HTTP framework with first-class schema validation, an encapsulation model for cross-cutting concerns (auth, CORS, rate limiting, DB, observability), and built-in OpenAPI generation. The team already runs Fastify elsewhere in the monorepo.
Decision#
Build the API on Fastify 5 using its plugin model:
buildServer()(src/app.ts) is the single composition root. It registers cross-cutting plugins in order — request context, error handler, security headers, CORS, rate limit, database, redis, auth, swagger — before the route groups, so every route inherits them.- Plugins are wrapped with
fastify-pluginand pinned tofastify: '5.x'so a version mismatch fails fast at boot rather than mysteriously at runtime (this exact mismatch — a4.xconstraint on a 5.x app — was a real startup bug found and fixed during the persistence work). - Routes are grouped by domain under a
/v1prefix (registerRoutes), each group a self-contained plugin receiving its dependencies (config, verifiers, weather provider) as options.
Consequences#
- + Cross-cutting behaviour is declared once and uniformly applied; ordering is explicit and reviewable.
- + Route groups are independently testable and composable; dependencies are injected per-group (enabling ADR-0005).
- + Schema-first routes feed OpenAPI generation for free (ADR-0003).
- − Plugin encapsulation/ordering has a learning curve;
fastify-pluginvs encapsulated registration must be chosen deliberately.