Production-ready FastAPI boilerplate with clean architecture, comprehensive observability, and enterprise-grade features
A production-grade FastAPI boilerplate designed for building scalable, maintainable APIs with enterprise features built-in. Perfect for SaaS applications, microservices, and complex business logic.
Built with:
- 🏗️ Clean Architecture - Clear separation of concerns across 4 layers
- 🆔 UUIDv7 - Time-ordered identifiers for distributed systems
- 🏢 Multi-Tenancy - Built-in tenant isolation (JWT with ES256)
- 📊 Full Observability - OpenTelemetry, structured logging, distributed tracing
- 🔄 Temporal Workflows - Durable task orchestration
- ✅ Comprehensive Testing - 1,069 tests with 84% coverage → detailed stats
Get running in 3 commands:
# 1. Install dependencies
pip install uv && uv sync --all-groups
# 2. Start services & run migrations
cp .env.example .env
docker-compose --profile infra up -d
make migrate
# 3. Start API
uv run python main.py
# → API: http://localhost:8000
# → Docs: http://localhost:8000/docs👉 Complete setup guide | Tutorials | Architecture
- When to Use This
- Features
- Architecture
- Documentation
- Technology Stack
- Project Structure
- Contributing
- License
| Use Case | Why It Fits |
|---|---|
| SaaS Applications | Multi-tenancy, security, scalability built-in |
| Microservices | Clean architecture, distributed tracing, correlation IDs |
| Complex Business Logic | Domain-driven design, clear layer separation |
| High-Performance APIs | Async throughout, Redis caching, connection pooling |
| Team Collaboration | Type safety, clear boundaries, comprehensive docs |
| Production Systems | Observability, error handling, graceful degradation |
- Simple CRUD APIs - Too much structure for basic REST operations
- Prototypes/MVPs - Consider simpler FastAPI templates for rapid experimentation
- Learning Projects - Start with official FastAPI tutorials first
- Single-page forms - Use lightweight frameworks
| Your Requirement | Use This | Consider Alternative |
|---|---|---|
| Multi-tenancy required | ✅ Yes | ❌ No |
| >10K requests/day expected | ✅ Yes | 🤷 Maybe |
| Background jobs needed | ✅ Yes | ❌ No |
| Team size >3 developers | ✅ Yes | 🤷 Maybe |
| Complex business rules | ✅ Yes | ❌ No |
| Production deployment | ✅ Yes | 🤷 Maybe |
| Just learning FastAPI | ❌ No | ✅ Yes |
| Simple CRUD only | ❌ No | ✅ Yes |
- ⚡ FastAPI - Modern async web framework with auto-generated docs
- 🐍 Python 3.12-3.14 - Latest Python with type parameter syntax
- 🏗️ Clean Architecture - 4-layer architecture (Domain → Application → Infrastructure → Presentation)
- 💉 Dependency Injection - Container-based DI with
dependency-injector - ✅ Type Safety - Full type hints throughout with MyPy validation
- 🗄️ PostgreSQL - Async database with SQLAlchemy 2.0
- 🔄 Redis - High-performance caching with compression (zstd)
- 🆔 UUIDv7 - Time-ordered, sortable UUIDs for distributed systems
- 📄 Cursor Pagination - Efficient pagination for large datasets
- 🔄 Database Migrations - Atlas for declarative schema management
- ⚙️ Temporal - Durable workflow orchestration with built-in observability
- 📬 Email Service - Async email sending with Mailpit for dev/testing
- 🔄 Async Tasks - Background job processing with retry logic
- 🔐 API Signature Validation - HMAC-SHA256 request signing for partner APIs
- 🛡️ Security Headers - CSP, HSTS, X-Frame-Options, etc.
- 🚦 Rate Limiting - Per-client rate limiting with Redis
- 📋 Log Sanitization - Automatic PII/secret removal from logs
- 🔒 Tenant Isolation - Multi-tenant data segregation via JWT
- 📊 OpenTelemetry - Distributed tracing with OTLP export
- 📝 Structured Logging - JSON logs with
structlog - 🔗 Correlation IDs - Cross-service request tracking
- 🔍 Trace Context Propagation - W3C Trace Context standard
- 📊 Request Context - Extract client IP, trace IDs from headers
- 🧪 Comprehensive Testing → detailed stats
- 🎯 Test Factories - Reusable test data factories
- 🔬 Property-Based Testing - Hypothesis strategies for edge cases
- 📚 Auto-Generated Docs - OpenAPI/Swagger UI
- 🐳 Docker Support - Complete dev environment with docker-compose
- 🔧 Pre-commit Hooks - Automated code quality (Ruff, MyPy)
- ⚡ Fast Package Manager - UV for 10-100x faster dependency resolution
- 🔌 Circuit Breaker - Fault tolerance for external services
- 💾 Redis Caching - Configurable TTL with compression
- 🔄 Connection Pooling - Efficient database connection management
- ♻️ Graceful Degradation - Fallback strategies for service failures
This boilerplate follows Clean Architecture principles with clear separation of concerns:
graph TB
Presentation["Presentation Layer<br/>FastAPI routes, schemas, DTOs"]
Application["Application Layer<br/>Use cases, orchestration, workflows"]
Infrastructure["Infrastructure Layer<br/>Database, cache, external APIs, implementations"]
Domain["Domain Layer<br/>Entities, value objects, business rules"]
Presentation --> Application
Application --> Domain
Infrastructure --> Domain
style Presentation fill:#e1f5ff
style Application fill:#fff4e1
style Domain fill:#f0ffe1
style Infrastructure fill:#ffe1f5
Key principles:
- Dependency Inversion - Inner layers don't depend on outer layers
- Single Responsibility - Each layer has one clear purpose
- Interface Segregation - Use interfaces/protocols for dependencies
- Repository Pattern - Abstract data access
- Unit of Work - Manage transactions consistently
👉 Complete architecture guide | Design decisions
- Quick Start - Get running in 5 minutes
- Installation Tutorial - Complete setup guide
- Your First API - Build your first endpoint
- API Reference - All endpoints documented
- Configuration - Environment variables
- Architecture - System design
- Testing Guide - Testing strategy
- Clean Architecture - Why this pattern?
- Design Decisions - ADRs and rationale
- Multi-Tenancy - Tenant isolation approach
- Observability - Telemetry strategy
| Technology | Version | Purpose |
|---|---|---|
| Python | 3.12-3.14 | Programming language |
| FastAPI | 0.121+ | Web framework |
| Pydantic | 2.12+ | Data validation |
| SQLAlchemy | 2.0+ | ORM & database toolkit |
| PostgreSQL | 16+ | Primary database |
| Redis | 7+ | Caching & rate limiting |
| Technology | Version | Purpose |
|---|---|---|
| Temporal | 1.8+ | Workflow orchestration |
| OpenTelemetry | 1.38+ | Distributed tracing |
| Atlas | Latest | Database schema migrations |
| UV | Latest | Fast package manager |
| Docker | Latest | Containerization |
| Technology | Version | Purpose |
|---|---|---|
| Pytest | 8.4+ | Testing framework |
| Ruff | 0.14+ | Linting & formatting |
| MyPy | 1.18+ | Static type checking |
| Pre-commit | 4.3+ | Git hooks |
| Hypothesis | Latest | Property-based testing |
python-fast-forge/
├── src/ # Source code
│ ├── domain/ # Domain layer (entities, business rules)
│ │ ├── models/ # Domain models
│ │ ├── exceptions.py # Domain exceptions
│ │ └── pagination.py # Pagination value objects
│ ├── app/ # Application layer (use cases)
│ │ ├── usecases/ # Business use cases
│ │ └── tasks/ # Background tasks
│ ├── infrastructure/ # Infrastructure layer (implementations)
│ │ ├── persistence/ # Database (SQLAlchemy)
│ │ ├── repositories/ # Data access repositories
│ │ ├── cache/ # Redis caching
│ │ ├── security/ # Security implementations
│ │ ├── telemetry/ # OpenTelemetry setup
│ │ └── patterns/ # Circuit breaker, etc.
│ ├── presentation/ # Presentation layer (API)
│ │ ├── api/ # FastAPI routes
│ │ ├── schemas/ # Request/response DTOs
│ │ └── mappers/ # DTO ↔ Domain mapping
│ ├── external/ # External service clients
│ ├── utils/ # Shared utilities
│ └── container.py # Dependency injection container
├── tests/ # Test suite
│ ├── unit/ # Unit tests (19 files)
│ ├── integration/ # Integration tests (9 files)
│ ├── factories.py # Test data factories
│ └── strategies.py # Hypothesis strategies
├── migrations/ # Atlas database migrations (SQL)
├── load_models.py # SQLAlchemy model loader for Atlas
├── atlas.hcl # Atlas migration configuration
├── config/ # Configuration files
├── docs/ # Documentation
│ ├── tutorials/ # Step-by-step tutorials
│ ├── how-to/ # Task-oriented guides
│ ├── reference/ # Technical reference
│ └── explanation/ # Deep dives & ADRs
├── main.py # API entry point
├── worker.py # Temporal worker
├── docker-compose.yml # Dev environment
└── pyproject.toml # Project configuration
# 1. Clone repository
git clone https://github.com/thaithienvanid/python-fast-forge.git
cd python-fast-forge
# 2. Install UV (fast package manager)
pip install uv
# 3. Install all dependencies (dev, test, security tools)
uv sync --all-groups
# 4. Copy environment file
cp .env.example .env
# 5. Start infrastructure (PostgreSQL, Redis, Temporal, Mailpit)
docker-compose --profile infra up -d
# 6. Install Atlas CLI (one-time setup)
curl -sSf https://atlasgo.sh | sh
# 7. Run database migrations
make migrate
# 8. Start API server (with hot reload)
uv run python main.py
# 8. (Optional) Start Temporal worker in another terminal
uv run python worker.py# Check API health
curl http://localhost:8000/health
# Expected response:
# {"status":"healthy","version":"0.1.0"}
# Visit interactive docs
open http://localhost:8000/docs| Service | URL | Purpose |
|---|---|---|
| API | http://localhost:8000 | Main API |
| API Docs | http://localhost:8000/docs | Swagger UI |
| ReDoc | http://localhost:8000/redoc | Alternative docs |
| Mailpit | http://localhost:8025 | Email testing |
| Temporal UI | http://localhost:8080 | Workflow dashboard |
| PostgreSQL | localhost:5432 | Database |
| Redis | localhost:6379 | Cache |
# Run all tests
make test
# Run with coverage report
make test-cov
# Run only unit tests
uv run pytest tests/unit/
# Run only integration tests
uv run pytest tests/integration/
# Run specific test file
uv run pytest tests/unit/test_user_model.py
# Run tests in parallel (faster)
uv run pytest -n auto# Install pre-commit hooks (auto-format, lint, type-check)
uv run pre-commit install
# Run linting
make lint
# Run type checking
make type-check
# Format code
make format
# Create new migration
make migrate-create m="Description"
# View migration status
make migrate-status
# Inspect schema
make schema-inspectThis boilerplate is production-ready with:
- ✅ Docker multi-stage builds
- ✅ Health checks
- ✅ Graceful shutdown
- ✅ Environment-based configuration
- ✅ Secrets management
- ✅ Horizontal scaling support
# Build production image
docker build -f Dockerfile -t my-api:latest .
# Run in production mode
docker-compose --profile infra --profile app up -dWe welcome contributions! Please see our Contributing Guide for details.
Quick links:
This project is licensed under the MIT License - see the LICENSE file for details.
Built with these amazing technologies:
- FastAPI - Modern Python web framework
- Temporal - Durable workflow engine
- SQLAlchemy - Python SQL toolkit
- OpenTelemetry - Observability framework
- Pydantic - Data validation
- Documentation: Full docs
- Issues: GitHub Issues
- Discussions: GitHub Discussions
⭐ Star this repo if you find it helpful!