Skip to content
Public template

About

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.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

FastAPI Essential

CI License: MIT

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.

What you get

  • 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 stable error_code
  • Layered modules: routes -> services -> repository, with interfaces.py as the API contract; a reference CRUD module to copy
  • Ops basics: settings with .env.example enforced 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

Requirements

  • Python 3.12
  • uv
  • Docker (optional, for Postgres, Redis and the full stack)

Quick start

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 --reload

Open 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.

Commands

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

Project structure

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

Architecture

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.

Documentation

Quality gate and CI

./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.

Working with AI agents

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.

Make it yours

  1. Set a real JWT_SECRET_KEY (production refuses the default) and review .env.example.
  2. Copy src/modules/example/item to start your first feature and register it in src/routes/v1/api.py and src/configs/models.py.
  3. Generate and commit your migrations (alembic/versions/ starts empty).
  4. Rename the project in pyproject.toml and APP_NAME.

License

MIT. See LICENSE.

About

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.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Used by

Contributors

Languages