Async FastAPI Sample (Modern Backend Template)

A production-ready FastAPI template designed for scalability, observability, and clean architecture.

It demonstrates a modern Python backend stack using:

• Clean Architecture (DDD-inspired)
• Docker-first development
• Observability (OpenTelemetry + Jaeger)
• Strong typing & linting (Ruff + Ty)
• Modern tooling (uv + mise)
• Fully automated dev workflow

---

✨ Features

• ⚡ FastAPI (async-first API framework)
• 🧱 Clean Architecture (domain / application / data / presentation)
• 🐘 PostgreSQL (asyncpg + SQLAlchemy 2 + SQLModel)
• 🔁 Alembic migrations
• 📦 Dockerize full stack (backend + postgres + observability stack)
• 📊 OpenTelemetry tracing (FastAPI + collector + Jaeger)
• 🧠 Strong typing (Ty)
• 🧹 Ruff for linting + formatting
• 🧪 Pytest + coverage + benchmarking
• 🔐 Security scanning (bandit + detect-secrets)
• 🧾 Conventional commits (Commitizen)
• 🚀 Developer experience via mise

---

🏗️ Architecture

This project follows a modular domain-driven structure:

src/
├── apps/
│   └── users/
│       ├── domain/         # Entities + DTOs (pure business logic)
│       ├── application/    # Use cases / services
│       ├── data/           # Repositories / DB layer
│       └── presentation/   # API routes (FastAPI)
│
├── core/
│   ├── settings.py
│   ├── base_service.py
│   ├── base_repository.py
│   └── deps.py
│
├── utils/
│   ├── logging_config.py
│   ├── middleware.py
│   ├── exceptions.py
│   └── pagination.py
│
├── migrations/            # Alembic migrations
└── main.py

---

🚀 Quick Start

1. Install tooling

This project uses mise:

mise install

---

2. Setup environment

mise run setup

This will:

• Install dependencies (uv)
• Setup pre-commit hooks

---

3. Start infrastructure

mise run up

This starts:

• Backend API
• PostgreSQL
• Observability stack (Jaeger + OpenTelemetry collector)

---

4. Run migrations

mise run migrate

---

5. Start development

mise run logs

or run backend shell:

mise run shell

---

📚 API Documentation

Once backend is running:

Swagger UI

mise run swagger

👉 http://localhost:8000/docs

---

🧪 Testing

Run all tests:

mise run test

Run with coverage:

mise run coverage

Output:

• Terminal coverage report
• HTML report → htmlcov/index.html

---

📊 Benchmarking

Run performance benchmarks:

mise run benchmark

---

🔐 Security

Run security checks:

mise run security

Includes:

• Bandit (static security analysis)
• Detect-secrets (secret scanning)

---

🧹 Code Quality

Format code

mise run fmt

Lint code

mise run lint

Fix lint issues

mise run lint-fix

Type check

mise run typecheck

Full check

mise run check

---

🐳 Docker Workflow

Start everything

mise run up

Stop everything

mise run down

Rebuild

mise run rebuild

Logs

mise run logs

Shell into backend

mise run shell

---

🗄️ Database

Run migrations

mise run migrate

Create migration

mise run makemigrations -m "your message"

Check migrations

mise run db-current
mise run db-history

---

🧠 Observability

This project includes full distributed tracing:

• OpenTelemetry SDK
• FastAPI instrumentation
• OTEL Collector
• Jaeger UI

Access Jaeger:

👉 http://localhost:16686

---

🧾 Commit Workflow

This project enforces Conventional Commits.

Interactive commit

mise run commit

Version bump + changelog

mise run bump

---

🧪 CI Pipeline (Local)

Simulate CI locally:

mise run ci

Runs:

• formatting
• linting
• typing
• tests
• security checks

---

🧰 Tech Stack

Layer	Tech
API	FastAPI
DB	PostgreSQL
ORM	SQLAlchemy + SQLModel
Migrations	Alembic
Observability	OpenTelemetry + Jaeger
Validation	Pydantic v2
Typing	Ty
Linting	Ruff
Testing	Pytest
Runtime	Uvicorn
Packaging	uv
Dev UX	mise

---

📦 Project Philosophy

This template is built around:

• Predictable structure
• Zero hidden magic
• Fast local iteration
• Production parity with Docker
• Strict typing + linting
• Observability by default

---

🧪 Example Endpoint Structure

users/
├── domain/        → pure logic
├── application/   → use cases
├── data/          → DB layer
└── presentation/  → API routes

Each layer is independent → easy testing, scaling, and refactoring.

---

🧼 Notes

• No global dependencies (everything via uv)
• No Node required
• Fully reproducible environments
• Designed for scaling into microservices