AI-Fastify-Template

4 months ago 9

Production-ready Fastify + TypeScript monorepo optimized for AI-assisted development

This template provides a production-ready foundation where AI coding agents autonomously generate complete backend APIs with automatically generated type-safe client SDKs using comprehensive guardrails that prevent technical debt and architectural violations.

Modern AI coding assistants are powerful but can introduce subtle bugs, architectural violations, or security issues. This template provides:

Immediate feedback loops for AI agents through fail-fast pipelines
Constraint-driven development that guides AI toward correct patterns
Comprehensive quality gates that catch issues before they reach production
Clear architectural boundaries that prevent spaghetti code

Why AI Development Needs Different Constraints

Traditional software quality relies on experienced developers making good decisions. AI agents have different failure modes that require systematic prevention:

🧪 The "Coverage Theater" Problem

// AI frequently writes tests that achieve 100% coverage but validate nothing: it('should calculate tax', () => { const result = calculateTax(100, 0.1); expect(result).toBeDefined(); // ✅ Passes expect(typeof result).toBe('number'); // ✅ Passes - 100% coverage! }); // Our mutation testing with Stryker catches this // When logic is mutated, the test still passes, revealing it's fake

🏗️ Architectural Drift Without Understanding

// AI doesn't understand why this is problematic: const config = { port: process.env.PORT || 3000, // ❌ No validation secret: process.env.JWT_SECRET, // ❌ Could be undefined }; // ESLint rules enforce proper patterns: const config = ConfigSchema.parse(process.env); // ✅ Validation required

⚡ Different Development Velocity

Human pace: Think → Code → Test → Review (minutes to hours)
AI pace: Generate → Validate → Iterate (seconds)
Our solution: Fast quality gates optimized for AI's rapid iteration

This template implements constraint-based development where quality comes from systematic guardrails, not developer experience.

Built for fully autonomous AI development workflows where AI agents generate complete applications while automated tooling provides type-safe client integration. The human role is limited to:

Requirements collaboration with AI agents (pulling from Linear via MCP)
Final approval of AI-generated implementations
Deployment decisions and production oversight

AI agents handle 100% of development:

Complete application development (backend APIs, testing, documentation)
Code generation, testing, and code review using Cursor IDE, Claude Code, and OpenAI Codex

Automated SDK generation provides:

Type-safe client libraries automatically generated from API specifications (via Fern)
Zero client integration overhead - consume APIs immediately with full IntelliSense
Contract enforcement - breaking API changes are caught at compile-time
Rapid prototyping - frontend teams get working client libraries instantly

This eliminates the traditional bottleneck where backend teams must manually write and maintain client SDKs, documentation, and coordinate API changes with frontend teams.

Node.js >= 20.0.0
pnpm >= 10.0.0

# Clone the repository git clone https://github.com/mkwatson/ai-fastify-template.git cd ai-fastify-template # Setup development environment (includes GitLeaks security scanner) pnpm setup:dev # Verify setup pnpm ai:quick

Manual GitLeaks Installation

If you need to install GitLeaks separately or the automatic installation fails:

# Install GitLeaks using the enterprise installation script pnpm setup:gitleaks # Or manually via package manager: # macOS: brew install gitleaks # Ubuntu/Debian: sudo apt-get install gitleaks # RHEL/CentOS: sudo yum install gitleaks

Note: GitLeaks is required for the pre-commit security scanning. The setup script automatically handles installation across different platforms.

# Start development server pnpm dev # Start all apps in development mode # Build and test pnpm build # Build all packages pnpm test # Run all test suites pnpm type-check # TypeScript compilation check # Quality assurance pnpm lint # Code formatting and linting (ESLint + Prettier) pnpm clean # Clean build artifacts

ai-fastify-template/ ├── apps/ # Applications ✅ │ └── backend-api/ # Fastify backend API ✅ ├── packages/ # Shared packages ✅ │ └── config/ # Configuration utilities ✅ ├── docs/ # Documentation ✅ │ ├── CONTRIBUTING.md # Contributing guidelines ✅ │ ├── DEVELOPMENT.md # Development workflow ✅ │ └── ARCHITECTURE.md # Architecture overview ✅ ├── turbo.json # TurboRepo configuration ✅ ├── pnpm-workspace.yaml # pnpm workspace configuration ✅ └── package.json # Root package configuration ✅

Category Tool Why Critical for AI Traditional Projects

Fast streaming API	Fastify + fastify-sse	AI needs real-time responses	Standard in many projects
Linting + Formatting	ESLint + Prettier + Custom Rules	AI-specific rules prevent common mistakes	Usually just formatting
Early type safety	TypeScript (strict)	AI can't use escape hatches like any	Often allows any types
Schema validation	Zod (bodies & env)	Mandatory - AI doesn't know trust boundaries	Often optional/selective
Security scanning	GitLeaks + audit-ci	AI might commit secrets without realizing	Manual review sufficient
Guard against spaghetti	dependency-cruiser	AI creates circular dependencies without understanding	Relies on code review
High-trust tests	Vitest + Coverage	Basic foundation for testing	Same usage
Mutation testing	Stryker (high standards)	Catches AI's "fake tests" that achieve coverage but test nothing	Rarely used (expensive)
Task caching	pnpm workspaces + TurboRepo	Sub-5-second feedback for AI's rapid iteration	Same usage

# Development workflow pnpm dev # Start all apps in development mode pnpm build # Build all packages pnpm clean # Clean build artifacts # Quality assurance pnpm test # Run all test suites pnpm test:watch # Run tests in watch mode pnpm test:coverage # Run tests with coverage report pnpm type-check # TypeScript compilation check

# Enterprise-grade quality pipeline pnpm ai:quick # Fast validation (lint + type-check) pnpm ai:check # Standard validation (includes security) pnpm ai:compliance # Full compliance validation pnpm ai:security # Security audit of dependencies # Security scanning pnpm security:scan # Run GitLeaks credential scanning pnpm setup:gitleaks # Install/update GitLeaks scanner # Advanced Quality Gates pnpm lint # Code formatting and linting (ESLint + Prettier) pnpm test:mutation # Run mutation tests with quality validation

Status: ✅ Active - Backend API implemented

Contains deployable applications:

backend-api/ - Production-ready Fastify server with TypeScript
Each app has its own package.json
Apps can depend on packages but not other apps
Apps should be thin, delegating logic to packages

Packages Directory (packages/)

Status: ✅ Active - Configuration utilities implemented

Contains shared libraries:

Reusable code across apps
Can depend on other packages
Should have clear, focused responsibilities

# pnpm-workspace.yaml packages: ['apps/*', 'packages/*']

# Create new app mkdir apps/my-app cd apps/my-app pnpm init # Create new package mkdir packages/my-package cd packages/my-package pnpm init

Working with Dependencies

# Add dependency to specific package pnpm add --filter my-app fastify # Add dev dependency to workspace root pnpm add -Dw typescript # Install dependencies for all packages pnpm install

Constraint-driven development guides AI toward correct patterns
Immediate feedback loops through fail-fast pipelines
Clear architectural boundaries prevent violations
Comprehensive validation catches AI-generated errors

Quality Gates (Implemented)

Strict TypeScript - No any types, comprehensive checking with type-aware ESLint rules
Runtime Validation - Zod schemas for all environment variables and request inputs
Import Graph Validation - dependency-cruiser prevents circular dependencies and enforces architecture
Comprehensive Testing - Unit, integration tests with high-standard mutation testing

Security First (Implemented)

Environment variable validation with Zod schemas
Input sanitization and validation at all API boundaries
GitLeaks pre-commit scanning for credential detection
Dependency vulnerability scanning with audit-ci

This template is in active development. Current state:

✅ Foundation Complete

Monorepo structure with pnpm + TurboRepo
Comprehensive documentation
AI-first development guidelines

✅ Backend API Complete (MAR-11)

Production-ready Fastify server with TypeScript
Strict TypeScript configuration with enterprise standards
Comprehensive test setup with Vitest
Development and production scripts

✅ Quality Tooling Complete

dependency-cruiser for architectural validation
Mutation testing with Stryker for test quality validation
Zod validation patterns for environment and inputs
Comprehensive testing framework with Vitest
CI/CD pipeline with GitHub Actions

Fast Quality Validation

# Quick validation during development pnpm ai:quick # Lint + type-check (fast) pnpm ai:check # + dependency validation pnpm ai:compliance # Full quality pipeline

Getting Started

Follow the Quick Start guide above
The backend API is already implemented and ready to use
Refer to docs/ for detailed development guidelines

# Advanced turbo commands for debugging pnpm build --verbosity=2 # Verbose build output with detailed logs pnpm clean # Clear build artifacts and cache turbo build --dry-run # See what would run without executing

🤖 AI-First Development Workflow

This template is specifically designed for autonomous AI development where AI agents perform all coding tasks. We support three primary AI coding tools—OpenAI Codex, Anthropic's Claude Code, and Cursor IDE.

AI Agent Guidelines Distribution

All AI coding agents receive the same comprehensive guidelines from AGENTS.md:

OpenAI Codex: Direct access to @AGENTS.md
Cursor IDE: Accesses via @.cursor/rules/default.mdc → references AGENTS.md
Claude Code: Accesses via @CLAUDE.md → imports AGENTS.md

This ensures 100% consistency across all AI coding tools with a single source of truth.

Requirements Gathering: AI agents pull tickets from Linear (via MCP integration)
Complete Development: AI agents generate full applications (APIs, tests, documentation) with full TypeScript safety
Automated SDK Generation: Fern automatically generates type-safe client SDKs from API specifications
Quality Validation: Comprehensive automated quality gates ensure code quality
AI Code Review: AI agents perform thorough code review and validation
Human Approval: Humans review final output and approve for deployment

Key Principle: Humans specify requirements and approve results. AI agents handle 100% of development implementation, while automated tooling provides seamless client integration.

Guidelines integrate with our quality pipeline:

pnpm ai:quick # Quick validation (lint + type-check) pnpm ai:check # Standard validation (includes security) pnpm ai:compliance # Full compliance validation

Always edit AGENTS.md for shared guidelines. Tool-specific files should remain minimal imports/references.

See CONTRIBUTING.md for detailed guidelines.

This project is licensed under the MIT License - see the LICENSE file for details.

Ready to build AI-powered applications? This template provides the complete foundation you need with a production-ready Fastify backend, comprehensive testing, and AI-optimized development workflows.

Read Entire Article