AGENTS.md — Fastify REST API

A typed JSON REST API on Node.js where every route declares its request and response schema, so validation, serialisation and docs come from one source.

Setup and commands

• dev: pnpm tsx watch src/server.ts
• lint: pnpm eslint . && pnpm tsc --noEmit
• test: pnpm vitest run
• build: pnpm tsc -p tsconfig.build.json
• deploy: docker build -t api . && docker push
• install: pnpm install --frozen-lockfile

Project structure

• src/app.ts — Builds the Fastify instance and registers plugins; no listen() here so tests can import it
• src/server.ts — Entry point: reads config, calls listen(), handles shutdown signals
• src/plugins/ — Cross-cutting plugins: auth, database pool, rate limit, security headers, error handler
• src/routes/ — One folder per resource with routes.ts, schema.ts and service.ts
• src/db/ — Drizzle schema, migrations and the query helpers
• src/config.ts — Environment parsing and validation at startup
• test/ — Integration tests per resource, using app.inject and a containerised database

Code style

• Files: kebab-case.ts
• Tests: *.test.ts beside the module; test/<resource>.int.test.ts for integration
• Branches: type/short-description, e.g. feat/orders-refund

Code

• Prefer small, pure functions and explicit types at module boundaries. (Easier to test, review and change.)
• Keep handlers thin: parse, call a service function, return. Business logic lives in service.ts and takes plain arguments. (Services can be unit-tested without a request object.)
• Register cross-cutting concerns as plugins with fastify-plugin only when they must be visible to sibling scopes. (Encapsulation keeps one resource’s hooks from silently applying to another.)

Components

• Components read design tokens; no raw hex values, pixel sizes or font names in component code. (One token change restyles the product.)

Data

• Analytics events are object_action in snake_case and come from the experience skill’s measures. (Names stay consistent across teams and tools.)
• Every route declares JSON schemas for params, querystring, body and each response status, using TypeBox or Zod type providers. (Fastify validates input and strips unknown output fields from the same schema, so nothing undeclared leaks.)

Errors

• Every async action has loading, empty, error and success states, matching the experience skill. (Unhandled states are where users get stuck.)
• Throw typed HTTP errors and let one setErrorHandler map them to a problem+json body; never send stack traces outside development. (Clients get a stable error shape and attackers get nothing useful.)

Security

• Secrets never live in the repository; read them from the environment or a secret store. (A leaked key outlives the commit that removed it.)
• Validate every input on the server, even when the client already did. (Clients can be bypassed.)
• Web pages ship a Content-Security-Policy, HSTS, X-Frame-Options and nosniff. (Cheap protection against the most common attacks.)
• Authenticate in an onRequest hook and authorise inside the service using the caller’s id, never an id taken from the body. (Ownership checks that rely on client input are the most common API flaw.)

Performance

• Set bodyLimit, connection and request timeouts, and a pool size per instance; use the logger at info level with redaction of auth headers. (Bounded resources keep one slow client from starving the process.)

Accessibility

• Use native elements first; add ARIA only when no native element fits. (Native controls bring keyboard and screen-reader support for free.)

Design and journeys

This stack has no UI; design skills do not apply.

When a Celestial experience skill is in use, give each journey one end-to-end test (happy path plus its error and empty states) and name analytics events object_action from its measures.

Testing and checks (must pass before a pull request)

Pull requests

• Branching: Trunk-based: short-lived branches off main, squash-merged within two days.

Review checklist

• Correctness: does it do what the issue asks, including edge cases?
• Readability: could a new teammate change it safely?
• Architecture: is it in the right place, with the right boundaries?
• Security: inputs, secrets, permissions, dependencies
• Performance: budgets, queries, bundle size
• Tests fail when the code is broken (flip a condition and re-run)
• One approving review; two for auth, payments, migrations or data deletion
• Reviewer reads the OpenAPI diff before the code diff

Definition of done

• Acceptance criteria met and demoed on the preview link
• Tests added for new behaviour and every state
• Accessibility and performance gates green
• Analytics events named from the experience skill
• Docs or changelog updated when behaviour changes
• Route has request and response schemas for every status it returns
• Integration test covers success, validation failure and unauthorised access

Release

• Small pull requests (aim for under 400 changed lines)
• CI green before review
• Squash-merge to main; main is always deployable
• Every release has a written rollback path
• Merge to main builds an image and deploys with a rolling update
• Migrations are additive and run before the new code; destructive changes ship a release later

Incidents

• Roll back by redeploying the previous image tag
• Write a blameless note within 48 hours: what happened, impact, fix, prevention

Generated from the Celestial engineering skill “Fastify REST API” (engineering core v1.0, checked 2026-10-26).