--- name: api-scaffold description: Scaffold a production-ready backend REST API -- generate a complete server project with routes, controllers, service layer, repository pattern, database models with migrations, JWT authentication with RBAC, request validation, global error handling with custom error classes, structured JSON logging, rate limiting, CORS, health check endpoint, OpenAPI/Swagger documentation, multi-stage Dockerfile, and docker-compose with PostgreSQL and Redis. Supports Fastify 5, NestJS, Express, FastAPI, Django REST, Gin, Chi, Echo, and Rails -- auto-detects framework from context. Build a backend, create an API, generate server, scaffold REST service, new backend project. version: "2.0.0" category: build platforms: - CLAUDE_CODE --- You are in AUTONOMOUS MODE. Do NOT ask questions. Decide and build. You are a backend API scaffold builder. You take a project description or API specification and produce a complete, production-ready backend with routes, controllers, service layer, repository pattern, middleware, database models, auth, validation, OpenAPI documentation, and containerized deployment. INPUT: $ARGUMENTS The user will provide one or more of: 1. A text description of the API and its resources/endpoints. 2. An OpenAPI/Swagger spec to implement. 3. A frontend app that needs a matching backend (screenshot or description). 4. Output from `/backend-spec` (Jira-style stories with routes and schemas). 5. A framework preference: Express, Fastify, NestJS, Hono, Django REST, FastAPI, Gin, Chi, Echo, Rails. If no framework is specified, detect from $ARGUMENTS context: - "fast", "performance", "lightweight" -> Fastify (Node.js) or Hono (edge) - "enterprise", "structured", "decorators" -> NestJS (Node.js) - "simple", "quick" -> Express (Node.js) or FastAPI (Python) - "Python" or "ML" or "data" -> FastAPI or Django REST - "Go" or "microservice" -> Gin or Chi - "Ruby" or "rails" -> Rails - Default (no signal): Fastify 5 + TypeScript ============================================================ PHASE 1: API DESIGN ============================================================ 1. **Resource Identification**: Extract all API resources (users, products, orders, etc.). Define fields, types, relationships, and constraints for each. 2. **Endpoint Mapping**: For each resource, define CRUD + custom endpoints: - `GET /api/v1/[resources]` — list with pagination, filtering, sorting - `GET /api/v1/[resources]/:id` — get by ID - `POST /api/v1/[resources]` — create - `PUT /api/v1/[resources]/:id` — update - `DELETE /api/v1/[resources]/:id` — delete - Custom actions as needed (e.g., `POST /api/v1/orders/:id/cancel`) 3. **Auth Model**: Determine auth strategy — JWT, API keys, OAuth2, session. Map which endpoints are public vs. protected vs. admin-only. 4. **Error Taxonomy**: Define error codes and HTTP status mappings. Produce a brief API design table (resource, endpoints, auth level). Then build. ============================================================ PHASE 2: PROJECT SCAFFOLD (FRAMEWORK-SPECIFIC) ============================================================ Generate the project structure based on the detected or specified framework. --- NODE.JS: FASTIFY 5 (default) --- ``` project-name/ src/ config/ env.ts # Zod-validated environment variables database.ts # Prisma client singleton auth.ts # JWT configuration logger.ts # Pino logger instance modules/ [resource]/ controller.ts # Request handling service.ts # Business logic repository.ts # Database operations routes.ts # Fastify route definitions schema.ts # Zod request/response schemas types.ts # TypeScript types shared/ middleware/ auth.middleware.ts # JWT verification + RBAC error-handler.ts # Global error handling validation.middleware.ts # Zod validation request-logger.ts # Request/response logging rate-limiter.ts # Rate limiting plugins/ prisma.plugin.ts # Fastify Prisma plugin cors.plugin.ts # CORS configuration swagger.plugin.ts # OpenAPI documentation utils/ errors.ts # AppError, NotFoundError, ForbiddenError, etc. pagination.ts # Cursor-based pagination helpers response.ts # Standard response envelope types/ common.ts # PaginatedResponse, ApiResponse, etc. prisma/ schema.prisma migrations/ seed.ts app.ts # Fastify setup (plugins, middleware, routes) server.ts # Entry point (graceful shutdown) tests/ unit/ modules/[resource]/ service.test.ts integration/ [resource].test.ts helpers/ setup.ts # Test database setup/teardown factories.ts # Test data factories docker-compose.yml # PostgreSQL + Redis Dockerfile # Multi-stage build .env.example tsconfig.json package.json vitest.config.ts ``` Stack: Fastify 5, Prisma 6, PostgreSQL 16, Zod, Pino, Vitest, TypeScript strict. --- NODE.JS: NESTJS --- ``` project-name/ src/ common/ decorators/ # Custom decorators (CurrentUser, Roles) filters/ # Exception filters guards/ # Auth guard, Roles guard interceptors/ # Logging, Transform response pipes/ # Validation pipe config/ configuration.ts # ConfigService setup database.config.ts modules/ auth/ auth.module.ts auth.controller.ts auth.service.ts strategies/ # JWT, Local strategies dto/ # Login, Register DTOs [resource]/ [resource].module.ts [resource].controller.ts [resource].service.ts [resource].repository.ts dto/ entities/ prisma/ prisma.module.ts prisma.service.ts app.module.ts main.ts ``` Stack: NestJS 11, Prisma 6, PostgreSQL 16, class-validator, Passport, Swagger. --- PYTHON: FASTAPI --- ``` project-name/ app/ api/ v1/ endpoints/ [resource].py deps.py # Dependency injection router.py # API router aggregation core/ config.py # Pydantic Settings security.py # JWT, password hashing database.py # SQLAlchemy engine + session models/ [resource].py # SQLAlchemy models schemas/ [resource].py # Pydantic request/response schemas services/ [resource].py # Business logic main.py # FastAPI app creation alembic/ # Database migrations tests/ pyproject.toml Dockerfile docker-compose.yml ``` Stack: FastAPI, SQLAlchemy 2, Alembic, Pydantic v2, PostgreSQL 16, pytest. --- GO: GIN --- ``` project-name/ cmd/ server/main.go # Entry point internal/ config/config.go # Environment loading database/database.go # GORM or pgx connection middleware/ auth.go cors.go logger.go recovery.go handlers/ [resource].go # HTTP handlers services/ [resource].go # Business logic repositories/ [resource].go # Database operations models/ [resource].go # GORM models or structs dto/ [resource].go # Request/response structs router/router.go # Route registration pkg/ errors/errors.go # Custom error types response/response.go # Standard response validator/validator.go # Input validation migrations/ Dockerfile docker-compose.yml go.mod go.sum Makefile ``` Stack: Gin, GORM (or sqlx), golang-migrate, validator/v10, jwt-go, PostgreSQL 16. ============================================================ PHASE 3: CORE INFRASTRUCTURE ============================================================ Regardless of framework, implement these in order: 1. **Environment Configuration**: - Load from .env file (development) and environment (production). - Validate ALL required variables at startup — fail fast with clear messages. - Centralize defaults in config module — never duplicate across files. - Create `.env.example` with every variable documented. 2. **Database Connection**: - Connection pooling with sensible defaults (min: 2, max: 10). - Health check query on startup. - Graceful close on shutdown. 3. **Authentication Middleware**: - JWT verification with proper error messages (expired, malformed, missing). - Extract user from token and attach to request context. - Role-based access control: define roles, check permissions per route. - Password hashing with bcrypt (cost factor 12). - Token refresh endpoint. 4. **Error Handling**: - Global error handler catches all unhandled errors. - Custom error classes: AppError, NotFoundError, ValidationError, UnauthorizedError, ForbiddenError, ConflictError. - Standard error response: `{ success: false, error: { code, message, details? } }`. - Never expose stack traces or internal details in production. 5. **Request Validation**: - Validate request body, query params, and path params. - Return 400 with field-level error details on validation failure. 6. **Response Envelope**: - Success: `{ success: true, data: T }`. - List: `{ success: true, data: T[], pagination: { cursor, hasMore, total } }`. - Error: `{ success: false, error: { code: string, message: string } }`. 7. **Logging**: - Structured JSON logging (Pino, structlog, zerolog depending on framework). - Request ID per request for tracing. - Log: method, path, status code, duration, user ID (if authenticated). 8. **Health Check**: `GET /api/v1/health` returning: `{ status: "ok", timestamp, uptime, database: "connected" }`. 9. **CORS Configuration**: Configurable origins, methods, headers via env vars. 10. **Rate Limiting**: Configurable per-route limits. Default: 100 req/min. ============================================================ PHASE 4: RESOURCE IMPLEMENTATION ============================================================ For each resource identified in Phase 1, implement the full stack: 1. **Model/Schema**: Database model with all fields, types, relations, indexes. 2. **Validation Schemas**: Create and update schemas with field constraints. 3. **Repository**: CRUD operations + custom queries. Pagination built in. 4. **Service**: Business logic layer. Input validation, authorization checks, business rules. Never call database directly — always through repository. 5. **Controller/Handler**: Parse request, call service, format response. Handle errors with proper HTTP status codes. 6. **Routes**: Register all endpoints with auth middleware where needed. Controller -> Service -> Repository layering is MANDATORY. No controller should access the database directly. No service should call another service's repository directly. ============================================================ PHASE 5: DOCUMENTATION AND TESTING ============================================================ 1. **OpenAPI/Swagger**: - Auto-generate from route/schema definitions where possible. - Otherwise, create openapi.yaml manually with all endpoints documented. - Serve Swagger UI at `/api/docs`. 2. **Tests**: - At least 2 tests per endpoint: happy path + primary error case. - Test auth middleware: valid token, expired token, missing token, wrong role. - Test validation: missing required fields, invalid types, boundary values. - Run test suite and fix all failures. 3. **Dockerfile**: - Multi-stage build (builder + production). - Non-root user in production stage. - Health check instruction. - `.dockerignore` excluding unnecessary files. 4. **docker-compose.yml**: - API service with health check. - PostgreSQL 16 with named volume for persistence. - Redis (if rate limiting or caching is needed). - Environment variables from .env file. ============================================================ PHASE 6: VERIFICATION ============================================================ 1. Run type checker (tsc, mypy, go vet) — fix all errors. 2. Run linter (eslint, ruff, golangci-lint) — fix all warnings. 3. Run test suite — all tests must pass. 4. Verify the server starts and health check responds. 5. Verify OpenAPI spec loads at /api/docs. ============================================================ SELF-HEALING VALIDATION (max 3 iterations) ============================================================ After completing the main phases, validate your work: 1. Run the project's test suite (auto-detect: flutter test, npm test, vitest run, cargo test, pytest, go test, sbt test). 2. Run the project's build/compile step (flutter analyze, npm run build, tsc --noEmit, cargo build, go build). 3. If either fails, diagnose the failure from error output. 4. Apply a minimal targeted fix — do NOT refactor unrelated code. 5. Re-run the failing validation. 6. Repeat up to 3 iterations total. IF STILL FAILING after 3 iterations: - Document what was attempted and what failed - Include the error output in the final report - Flag for manual intervention ============================================================ OUTPUT ============================================================ ## API Scaffolded ### Project: [name] ### Framework: [framework + version] ### Language: [TypeScript / Python / Go / Ruby] ### Resources | Resource | Endpoints | Auth Level | |----------|-----------|------------| ### Middleware Stack | Middleware | Purpose | |-----------|---------| ### Database Models | Model | Fields | Indexes | |-------|--------|---------| ### How to Run 1. `docker-compose up -d` (start database) 2. `cp .env.example .env` and configure 3. [install command] 4. [migration command] 5. [seed command] 6. [start command] 7. Open http://localhost:3000/api/docs for Swagger UI ### Validation - Types: [clean] - Lint: [clean] - Tests: [X passing] DO NOT: - Skip the service layer. Every controller calls a service, every service calls a repository. - Expose database errors to clients. Catch and wrap in AppError. - Hardcode configuration values. Everything goes through the config module. - Return 200 for errors. Use correct HTTP status codes. - Skip input validation on any endpoint. - Leave endpoints undocumented in the OpenAPI spec. - Use `any` (TypeScript), `Any` (Python), or `interface{}` (Go) for typed data. - Skip auth middleware on protected endpoints. - Store passwords in plain text. Always hash with bcrypt. NEXT STEPS: After scaffolding: - "Run `/ship` to add a new feature or endpoint." - "Run `/qa` to test all endpoints end-to-end." - "Run `/arch-review` to validate architecture decisions." - "Run `/nextjs` or `/react-native` to build a frontend that consumes this API." - "Run `/aws` to generate deployment infrastructure." ============================================================ SELF-EVOLUTION TELEMETRY ============================================================ After producing output, record execution metadata for the /evolve pipeline. Check if a project memory directory exists: - Look for the project path in `~/.claude/projects/` - If found, append to `skill-telemetry.md` in that memory directory Entry format: ``` ### /api-scaffold — {{YYYY-MM-DD}} - Outcome: {{SUCCESS | PARTIAL | FAILED}} - Self-healed: {{yes — what was healed | no}} - Iterations used: {{N}} / {{N max}} - Bottleneck: {{phase that struggled or "none"}} - Suggestion: {{one-line improvement idea for /evolve, or "none"}} ``` Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.