fastify-boilerplate AGENTS.md

AGENTS.md

Instructions for AI coding assistants (Cursor, Claude Code, GitHub Copilot, etc.)

Project overview

A production-ready Fastify 5 boilerplate using Clean Architecture, CQRS, DDD, and functional programming. TypeScript strict mode, ESM-only, Node >= 24 (native TS execution, no build step).

Quick reference

What	Where
Package manager	pnpm (never npm or yarn)
Linter + formatter	Biome (never ESLint or Prettier)
Validation after changes	pnpm check (runs biome check && tsc --noEmit)
Auto-fix formatting	pnpm format
Unit tests	pnpm test:unit (node:test)
E2E tests	pnpm test:e2e (Cucumber + Gherkin)
Architecture validation	pnpm deps:validate (dependency-cruiser)
DB migrations	pnpm db:migrate (DBMate)

Always run pnpm check after making changes. If formatting fails, run pnpm format first, then pnpm check.

Architecture

Layer boundaries (CRITICAL)

The dependency flow is strictly inward: Route → Handler → Domain → Repository.

src/
├── instrumentation.ts ← OpenTelemetry setup (loaded via --import before the app)
├── modules/         ← Feature code (vertical slices)
│   └── <feature>/
│       ├── commands/ ← State-changing operations
│       ├── queries/  ← Data-retrieval operations (idempotent)
│       ├── database/ ← Repository port (interface) + adapter (implementation)
│       ├── domain/   ← Business logic, types, errors
│       └── dtos/     ← Shared response schemas
├── server/          ← Fastify setup, plugins, DI wiring
└── shared/          ← Cross-cutting: CQRS, DB, exceptions, utils

Never import from src/shared/db/ or database/ inside handler files. Handlers interact with data exclusively through repository ports (interfaces). SQL belongs in repository files only.

Module independence

Modules should avoid importing directly from other modules. Cross-module communication uses the CQRS buses:

• Commands/queries for request-response
• Events for fire-and-forget notifications