Eve library

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

ADR

Revision 1

On this page

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).
  • + Schema-first routes feed OpenAPI generation for free (ADR-0003).
  • − Plugin encapsulation/ordering has a learning curve; fastify-plugin vs encapsulated registration must be chosen deliberately.