# ADR-0002: Fastify 5 with a plugin/route-group architecture

**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-plugin` and pinned to `fastify: '5.x'` so a
  version mismatch fails fast at boot rather than mysteriously at runtime (this
  exact mismatch — a `4.x` constraint on a 5.x app — was a real startup bug
  found and fixed during the persistence work).
- Routes are grouped by domain under a `/v1` prefix (`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](0005-injectable-external-providers.md)).
- **+** Schema-first routes feed OpenAPI generation for free
  ([ADR-0003](0003-openapi-first-documentation.md)).
- **−** Plugin encapsulation/ordering has a learning curve; `fastify-plugin` vs
  encapsulated registration must be chosen deliberately.
