A production-minded FastAPI starter: async SQLAlchemy and Alembic, Celery background tasks, JWT auth, a uniform response envelope with stable error codes, structured logging, metrics, tests and one quality gate.
Part of Essential: starter templates with the tooling, structure, docs and AI-agent guide already in place.
- FastAPI on Python 3.12 with async SQLAlchemy 2 (asyncpg) and Alembic
- Celery worker with Redis, with an example task and eager mode in tests
- JWT auth (HS256): register, login and
me, bcrypt password hashing; RS256/JWKS upgrade documented - Uniform responses: every endpoint returns
{success, message, data}; errors add a stableerror_code - Layered modules: routes -> services -> repository, with
interfaces.pyas the API contract; a reference CRUD module to copy - Ops basics: settings with
.env.exampleenforced by a test, JSON logging, request ids,/health,/ready, Prometheus/metrics - Tests without services: in-memory SQLite and eager Celery; contract tests guard naming, status codes and settings
- Ruff, ty, pytest, pre-commit, GitHub Actions, multi-stage Dockerfile and docker compose
- Docs and AGENTS.md for people and coding agents
Click Use this template on GitHub (or run gh repo create my-project --template essential-registry/fastapi-essential), then:
uv sync
cp .env.example .env
docker compose up postgres redis -d
uv run python -m src.scripts.migrate
uv run uvicorn src.main:app --reloadOpen http://localhost:8000/docs: register, log in, click Authorize, then create an item. Start a worker with uv run celery -A src.configs.celery:celery_client worker -l info. Tests need no services: uv run pytest.
| Command | What it does |
|---|---|
uv run uvicorn src.main:app --reload |
Run the API |
uv run celery -A src.configs.celery:celery_client worker -l info |
Run the Celery worker |
uv run python -m src.scripts.migrate |
Create the first migration if none exists, then upgrade |
uv run pytest |
Tests (SQLite in memory, Celery eager) |
./scripts/prepare.sh |
Fix mode: format, lint-fix, __init__.py files, install the git hook, then check |
./scripts/prepare.sh --check |
The non-mutating gate CI runs |
docker compose up --build |
API, worker, Postgres and Redis |
src/
main.py app factory: middleware, handlers, routers, metrics
configs/ settings, database, redis, celery, logger, middleware, health, models
utils/ response envelope, exceptions, status codes, auth, dependencies
routes/v1/ api.py (aggregates routers under /api/v1), init.py (/health, /ready)
scripts/migrate.py migration runner
modules/
auth/ register, login, me
example/item/ reference CRUD module: models, interfaces, repository,
services, payloads, routes, tasks, tests
tests/ contract tests; conftest.py (root) holds shared fixtures
alembic/ docs/ scripts/ Dockerfile docker-compose.yaml
Each feature is a module with strict layers: routes (validate, call, respond) -> services (business rules, typed exceptions) -> repository (queries only), with payloads building the response envelope and interfaces.py as the contract clients mirror. There is no admin/user split; the docs explain how to add one per feature if you need two audiences.
Full details: docs/01-architecture.md.
docs/01-architecture.md: layers, folders and how the pieces fitdocs/02-naming.md: naming conventions (enforced by tests)docs/03-errors-and-responses.md: the response envelope and error codesdocs/04-database-and-migrations.md: models, sessions and Alembicdocs/05-testing.md: how to test and what the gate checksdocs/06-background-tasks.md: Celery tasksdocs/07-docker-and-deploy.md: Docker, compose and deploymentdocs/08-authentication.md: JWT auth and moving to RS256docs/09-getting-started.md: setup and troubleshooting
./scripts/prepare.sh --check runs the __init__.py check, ruff format --check, ruff check, ty check and pytest. GitHub Actions runs it on every push and pull request and also builds the Docker image. Run ./scripts/prepare.sh once locally to fix problems and install the pre-commit hook, which runs the same gate.
AGENTS.md is the guide coding agents follow: commands, layout, conventions and a "never" list (CLAUDE.md points to it). .claude/ adds safe permissions, a formatter hook, a read-only reviewer agent and task skills. Commits always use your own git identity; the guide tells agents not to add attribution lines and not to commit unless asked.
- Set a real
JWT_SECRET_KEY(production refuses the default) and review.env.example. - Copy
src/modules/example/itemto start your first feature and register it insrc/routes/v1/api.pyandsrc/configs/models.py. - Generate and commit your migrations (
alembic/versions/starts empty). - Rename the project in
pyproject.tomlandAPP_NAME.
MIT. See LICENSE.