Tech stack

Project layout

fastapi-boilerplate/
├── .github/workflows/ci.yml      # Lint, type check, test, Docker build
├── alembic/
│   ├── env.py                    # Async migration environment, src-aware
│   ├── script.py.mako            # Modern Python 3.13 migration template
│   └── versions/                 # Generated revision files
├── src/
│   └── app/
│       ├── main.py               # FastAPI app factory + ASGI export
│       ├── api/
│       │   ├── deps.py           # Reusable Annotated[Depends(...)] aliases
│       │   ├── router.py         # Top-level /api router
│       │   └── v1/
│       │       ├── router.py     # v1 sub-router aggregator
│       │       └── endpoints/    # health.py, users.py, …
│       ├── core/
│       │   ├── config.py         # pydantic-settings Settings class
│       │   ├── logging.py        # structlog configuration
│       │   ├── exceptions.py     # AppException hierarchy
│       │   ├── exception_handlers.py  # FastAPI handlers → ProblemDetail
│       │   ├── middleware.py     # Request-id / access-log middleware
│       │   └── lifespan.py       # Startup/shutdown lifecycle
│       ├── db/
│       │   ├── base.py           # DeclarativeBase + naming convention
│       │   ├── mixins.py         # TimestampMixin
│       │   └── session.py        # Async engine + sessionmaker + get_session
│       ├── models/               # SQLAlchemy ORM models
│       ├── repositories/         # Data access (CRUD + queries)
│       ├── schemas/              # Pydantic v2 request/response models
│       └── services/             # Business logic
├── tests/
│   ├── conftest.py               # AsyncClient + ephemeral DB fixtures
│   ├── unit/                     # Fast, isolated tests
│   └── integration/              # End-to-end tests against the ASGI app
├── .env.example                  # Documented environment variables
├── .pre-commit-config.yaml
├── .python-version               # 3.13
├── Dockerfile                    # Multi-stage build with uv
├── docker-compose.yml            # API + Postgres with healthchecks
├── Makefile                      # Common developer commands
├── alembic.ini
├── pyproject.toml                # Single source of truth for tooling
└── README.md

Quick start

Prerequisites

• Docker (for the bundled Postgres) — everything else is installed by make setup.
• Optional: a system Python ≥ 3.11 to bootstrap uv (any modern distro qualifies).

One-command bootstrap

git clone <your-repo-url>
cd fastapi-boilerplate

make setup       # installs uv + Python 3.13, creates .env, starts Postgres, installs deps, runs migrations
make dev         # auto-reload server on http://localhost:8000

make setup is idempotent — safe to re-run any time. Under the hood it composes these granular targets, each of which you can call on its own:

Manual setup (if you'd rather wire it yourself)

git clone <your-repo-url>
cd fastapi-boilerplate

# 1. uv + Python
curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.13

# 2. Dependencies
uv sync --all-extras

# 3. Environment
cp .env.example .env
$EDITOR .env

# 4. Postgres (or point .env at an existing instance)
docker compose up -d db

# 5. Migrations + run
uv run alembic upgrade head
uv run uvicorn app.main:app --reload

The API is now live at http://localhost:8000:

• Swagger UI → http://localhost:8000/docs
• ReDoc → http://localhost:8000/redoc
• OpenAPI → http://localhost:8000/api/openapi.json
• Health → http://localhost:8000/api/v1/health

Run the full stack with one command

docker compose up --build

This starts Postgres and the API with healthchecks. Migrations run automatically against the configured DB the first time you make migrate inside the container, or you can bake the call into a startup script.

Configuration

All settings are validated at startup by Settings. See .env.example for the documented list. Highlights:

Environment behaviour

• local / development → /docs and /redoc enabled, full SQL echo opt-in.
• production → docs disabled, JSON logs recommended, generic 500 messages.
• test → used by the pytest fixtures; auto-skips DB connectivity check at startup.

Development workflow

make install        # uv sync --all-extras
make dev            # uvicorn with --reload
make check          # ruff format + ruff lint + mypy
make test           # pytest
make test-cov       # pytest with coverage

Pre-commit hooks (recommended)

uv run pre-commit install
uv run pre-commit run --all-files

Hooks run the same ruff, ruff format, and mypy that CI runs, so green locally ⇒ green in CI.

Database migrations

Alembic is preconfigured for async PostgreSQL and the src/ layout.

make makemigration MSG="add posts table"   # autogenerate from models
make migrate                                # apply migrations
make downgrade                              # roll back one revision
make db-revision                            # show current head

Migration scripts are auto-formatted with ruff via the post_write_hooks in alembic.ini. Migration files in alembic/versions/ are not committed by default — set up your own policy for your team.

Testing

Tests run against an in-memory SQLite database via aiosqlite, so the suite is fast and hermetic.

make test
make test-cov
uv run pytest tests/unit -m unit            # unit tests only
uv run pytest tests/integration -m integration

The client fixture builds the FastAPI app with dependency_overrides[get_session] pointing at the test session, and drives it through httpx.AsyncClient + asgi-lifespan — no real network, full lifespan events.

Code quality

All tooling is configured in pyproject.toml:

• Ruff runs a broad rule set (E, W, F, I, B, C4, UP, N, ASYNC, S, SIM, RUF, PL, PT, RET, PTH, TCH, …) plus formatting.
• mypy runs in strict mode with the Pydantic plugin enabled.
• pytest is configured with strict markers, strict config, and tracebacks trimmed for readability.

CI fails on any of: format drift, lint findings, type errors, or test failures.

Docker

The included Dockerfile is a multi-stage build:

1. builder — uses the official uv image to resolve dependencies into a .venv directory.
2. runtime — python:3.13-slim-bookworm, non-root user, healthcheck against /api/v1/health.

The accompanying `docker-compos

🚀 Production-grade FastAPI template • JWT auth • Rate limiting • Async PostgreSQL & Redis • OpenTelemetry observability (Prometheus, Grafana, Tempo) • Alembic • Docker • Gunicorn + Uvicorn • Async Ready • RFC-Compliant API Responses • Enterprise Security Patterns