Observability 📊

This template includes a production-grade OpenTelemetry observability setup designed for real-world systems:

• Automatic FastAPI instrumentation
• Distributed tracing with Tempo
• Golden Signals dashboards in Grafana
• Prometheus metrics via OpenTelemetry
• Custom application & rate-limiter visibility

Observability Stack

👉 All observability details live here: 📄 docs/OBSERVABILITY.md

Tech Stack 🛠️

Project Structure 🌳

The repository follows a layered architecture — each request flows api → services → crud → models, with schemas for I/O validation. This keeps HTTP concerns, business logic, and persistence cleanly separated and easy to test in isolation.

app/
├── api/            # Routers + request dependencies (user, todo, health)
├── services/       # Business logic (orchestrates crud + auth)
├── crud/           # Async SQLAlchemy data-access functions
├── models/         # SQLAlchemy ORM models
├── schemas/        # Pydantic request/response schemas
├── core/           # Settings, database, auth, exceptions, middleware, logging
├── utils/          # Rate limiter dependency
├── observability/  # OpenTelemetry telemetry, metrics, instrumentation
├── alembic/        # Migration environment & versions
└── main.py         # App factory, middleware wiring, exception handlers, lifespan

k8s/                # Kustomize base + dev/staging/prod overlays (deployment, ingress, HPA, NetworkPolicy, migration job)
docker/observability/  # Local Grafana/Tempo/Prometheus/OTel collector stack
docs/               # Observability guide, dashboards, screenshots
tests/              # unit / integration / e2e suites (pytest, fakeredis, hypothesis)
.github/workflows/  # CI: lint, mypy, migrations check, tests + coverage, docker build
docker-compose.yml  # One-command local stack (app + postgres + redis)
Dockerfile          # Canonical multi-stage image (lockfile-pinned)

Key Implementations 🔑

These patterns are the reason the template exists. Rather than paste code that drifts from the source, each links to the file that owns it.

Every endpoint returns the same envelope:

{ "status": "success", "message": "...", "data": { ... } }

…and errors are normalized by the handlers in main.py:

{ "status": "error", "message": "Validation Failed", "errors": [ ... ] }

Getting Started

Prerequisites

• Python 3.11+
• PostgreSQL 14+
• Redis 6+
• Docker (optional, but the fastest way to run the full stack)

Quickstart (Docker Compose) 🐳

The fastest path — builds the app image and starts the app, PostgreSQL, and Redis together. Migrations run automatically on container start.

make up      # build + start app + postgres + redis (detached)
make logs    # follow the app logs
make down    # stop and remove the stack

Then open http://localhost:8000/docs. To also run the observability stack (Grafana/Tempo/Prometheus/OTel), use make up-observability.

Installation (local Python)

git clone https://github.com/akhil2308/fastapi-large-app-template.git
cd fastapi-large-app-template

# Install uv (if not already installed)
pip install uv

# Sync dependencies and create virtual environment
# This installs all packages defined in pyproject.toml
uv sync --all-extras

# Install Git Hooks
# This ensures code quality checks run automatically on commit
uv run pre-commit install

Using Makefile

This project includes a Makefile with convenient commands. Run make help to see all available targets.

# Show all available commands
make help

# Install dependencies and setup git hooks
make install

# Development server
make dev

# Production server
make prod

# Run tests
make test

# Database migrations
make migrate
make migrate-create MSG="your migration message"
make migrate-check   # fail if models drifted from migrations

# Code quality
make check-env
make lint
make format
make typecheck

# Full CI pipeline
make ci

# Local Docker stack (app + postgres + redis)
make up
make down
make logs

# Observability stack (Grafana/Tempo/Prometheus/OTel)
make up-observability
make down-observability

# Clean generated files
make clean

Configuration

Set environment variables

cp .env.example .env
# Fill in DB, Redis, JWT, and other values

Alembic Commands (Migrations)

Generate new migration:

uv run alembic -c app/alembic.ini revision --autogenerate -m "message"

Apply migrations:

uv run alembic -c app/alembic.ini upgrade head

Running

Development:

uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Production:

./run.sh  # Applies migrations, then starts Gunicorn with uvicorn-worker

Docker 🐳

A single canonical multi-stage Dockerfile is used by both docker-compose and Kubernetes. It installs dependencies straight from uv.lock with uv sync --frozen (so the image can never drift from the committed lock), pins the Python base image, and runs as a non-root user.

docker build -t fastapi-large-app-template .

Kubernetes ☸️

Manifests live in k8s/ as a kustomize base + overlays — namespace, ConfigMap/Secret, Deployment, Service, Ingress, HPA, PodDisruptionBudget, a default-deny NetworkPolicy, and a migration Job, with dev/staging/prod overlays patching replicas, resources, and image tags per environment. The Deployment ships with startup/readiness/liveness probes, a hardened security context, and automountServiceAccountToken: false.

# 1. Build and push your image, then pin its tag in the overlay:
cd k8s/overlays/prod && kustomize edit set image \
  your-registry/fastapi-large-app-template=<registry>/<image>:<tag> && cd -

# 2. Fill in k8s/base/app/secret.yaml (JWT_SECRET_KEY, DB/Redis passwords) and
#    review k8s/base/app/configmap.yaml (ALLOWED_HOSTS, CORS_ORIGINS, OTEL endpoint).

# 3. Preview, then deploy (migration Job + all app resources):
kubectl kustomize k8s/overlays/prod
kubectl apply -k k8s/overlays/prod

See k8s/README.md for the full walkthrough.

Code Standards & Quality 🛡️

This project enforces code quality using Ruff (linter/formatter) and Mypy (static type checker).

Manual Checks

1. Linting & Formatting (Ruff)

# See what code Ruff wants to fix (Dry Run)
uv run ruff check .

# Actually fix the code (Auto-formatting & Import sorting)
uv run ruff check . --fix
uv run ruff format .

2. Static Type Checking (Mypy)

# Check for type errors
uv run m