npx specdriven add spec fastapi-serviceWhat's included
A production-grade async REST API built on FastAPI with PostgreSQL persistence via SQLAlchemy 2.0 and Alembic for schema migrations. Redis handles response caching and Celery task queuing. The spec ships with Docker Compose for local development and a multi-stage Dockerfile optimised for minimal production image size.
Authentication uses JWT bearer tokens with refresh token rotation. Rate limiting is applied per-endpoint via a Redis-backed middleware. All endpoints return consistent error envelopes conforming to RFC 9457 Problem Details.
Architecture
The project follows a clean layered structure: api/routers/ for route handlers, api/services/ for business logic, api/repositories/ for database access, and api/schemas/ for Pydantic models. Dependency injection wires services and repositories through FastAPI's Depends system, keeping handlers thin and testable.
Background tasks - email delivery, webhook dispatch, report generation - run in Celery workers that share the same SQLAlchemy session factory as the main app. Flower provides a real-time task monitoring UI accessible during development.
Getting started
Run npx specdriven add @specs/fastapi-service to scaffold the project. Rename .env.example to .env and set DATABASE_URL, REDIS_URL, and SECRET_KEY. Start all services with docker compose up -d, then run alembic upgrade head to apply migrations.
The development server reloads on file changes. Run pytest to execute the full test suite, which uses a dedicated test database and a Redis mock to keep tests fast and isolated.