fastify-backend-patterns

When to trigger

• Implementing a spec that names api work in the backend package.
• Authoring a new route handler (GET/POST/PUT/PATCH/DELETE) for a resource.
• Adding or modifying schema validation (request body, query params, response shape).
• Writing a new Fastify plugin (encapsulating a service, middleware, or feature module).
• Authoring a DB migration in the api migrations directory.
• Wiring a queue producer-side dispatch from a route handler.

Procedure

1. Place the route file under src/routes/<resource>/<verb>.ts per the package convention. Register the route via a Fastify plugin encapsulated in src/routes/<resource>/index.ts (or per the existing folder structure — read src/routes/ before adding new files).

2. Declare request and response schemas using Fastify's schema-validator integration (Zod or TypeBox per the project convention). Attach schemas to the route options object: { schema: { body: BodySchema, response: { 200: SuccessSchema, 4xx: ErrorSchema } } }. No unvalidated routes.

3. Register route via Fastify plugin: wrap route registrations in fastify.register(async function(instance) { instance.get(...) }). Plugin scope ensures encapsulation of prefix, decorators, and hooks.

4. Error handler: return a structured { error: string, code: string } (or the project's error shape) rather than throwing untyped errors. Use fastify.setErrorHandler at the plugin level for domain-specific error mappings. Never throw a raw JS Error from a route handler — map it to an HTTP status code with a structured body.

5. DB migration: place the migration file in migrations/<timestamp>-<slug>.sql (or the migration-tool format the project uses). Migrations are append-only and reversible — include a down migration or add a -- no-op down: <reason> comment. Never edit a landed migration.

6. Queue producer dispatch: follow the bullmq-jobs skill's producer pattern. Add a // dispatched-to: <queue-name> comment at each queue.add() call site so the consumer is traceable from the producer.