A comprehensive FastAPI template tutorial demonstrating Clean Architecture principles through a practical task management system. This project serves as a learning resource and production-ready template for building scalable, maintainable FastAPI applications with proper separation of concerns.
- Overview
- Clean Architecture Principles
- Project Structure
- Architecture Layers
- Tech Stack
- Getting Started
- Development Guide
This project implements a task management REST API following Clean Architecture. The architecture ensures:
- Separation of Concerns: Each layer has a single, well-defined responsibility
- Independence: Business logic is independent of frameworks, databases, and external agencies
- Testability: Easy to test each layer in isolation
- Maintainability: Changes in one layer don't affect others
- Flexibility: Easy to swap implementations (e.g., change databases or frameworks)
Dependencies flow inward only:
┌─────────────────────────────────────────────────┐
│ Drivers (FastAPI, HTTP) │
│ └─ Controllers, Routes, Schemas │
└─────────────────────────────────────────────────┘
↓ depends on
┌─────────────────────────────────────────────────┐
│ Adapters (Infrastructure) │
│ └─ Repository Implementations, ORM Models │
└─────────────────────────────────────────────────┘
↓ depends on
┌─────────────────────────────────────────────────┐
│ Use Cases (Application Business Logic) │
│ └─ CreateTask, CompleteTask, ListTasks │
└─────────────────────────────────────────────────┘
↓ depends on
┌─────────────────────────────────────────────────┐
│ Ports (Interfaces/Contracts) │
│ └─ TaskRepositoryInterface (ABC) │
└─────────────────────────────────────────────────┘
↓ depends on
┌─────────────────────────────────────────────────┐
│ Domain (Enterprise Business Rules) │
│ └─ Task Entity, TaskStatus, Priority │
└─────────────────────────────────────────────────┘
Key Principle: Inner layers never depend on outer layers. Outer layers depend on inner layers through abstractions (interfaces).
src/
├── domain/ # Domain Layer (Core Business Logic)
│ ├── entities/ # Business entities
│ ├── value_objects/ # Value objects (immutable data)
│ └── exceptions/ # Domain-specific exceptions
│ └── README.md # 📖 Detailed domain documentation
│
├── ports/ # Ports Layer (Interfaces)
│
├── use_cases/ # Use Cases Layer (Application Logic)
│
├── adapters/ # Adapters Layer (Infrastructure)
│ ├── repositories/ # Repository implementations
│ └── connection_engines/ # Database connections
│
├── drivers/ # Drivers Layer (External Interfaces)
│ ├── api/v1/ # REST API v1
│ ├── config/ # Configuration
│ ├── dependencies/ # Dependency injection
│ ├── exceptions_handlers/ # HTTP exception mapping
│ ├── helpers/ # Helper utilities
│
└── tests/ # Test Suite
├── unit_tests/ # Unit tests
├── e2e/ # End-to-end tests
└── conftest.py # Test fixtures
Purpose: Contains enterprise business rules and entities
Characteristics:
- Zero external dependencies
- Pure Python dataclasses
- Business logic lives here
- Framework-agnostic
📖 Read detailed Domain documentation
Purpose: Defines contracts/interfaces for external dependencies
Characteristics:
- Abstract Base Classes (ABC)
- No implementation details
- Defines what operations are needed, not how
📖 Read detailed Ports documentation
Purpose: Orchestrates domain entities to fulfill specific application use cases
Characteristics:
- Single Responsibility Principle: One use case = one operation
- Depends only on Ports (interfaces) and Domain
- Constructor injection for dependencies
- Single
execute()method
📖 Read detailed Use Cases documentation
Purpose: Implements ports/interfaces using specific technologies
Characteristics:
- Concrete implementations of repository interfaces
- Handles ORM models and database operations
- Converts between domain entities and persistence models
📖 Read detailed Adapters documentation
Purpose: Handles external communication (HTTP, CLI, etc.)
Characteristics:
- FastAPI routes and controllers
- Request/Response DTOs (Pydantic models)
- Exception handling and HTTP status mapping
- Dependency injection wiring
📖 Read detailed Drivers documentation
| Component | Technology |
|---|---|
| Framework | FastAPI |
| ASGI Server | Uvicorn |
| Database | SQLite |
| Async Driver | aiosqlite |
| ORM | SQLAlchemy |
| Migrations | Alembic |
| Validation | Pydantic |
| Testing | pytest + pytest-asyncio |
| Python | Python |
| Package Manager | uv |
Docker and Docker Compose (recommended)
- Clone the repository:
git clone [email protected]:lbenothman/fast-clean-api.git
cd fast-clean-api- Create a new .env file, based on .env.template and provided the needed values:
cp .env.template .env- Build and start the services:
make build
make upd- Run database migrations:
make alembic-db-upgrade- Access the API:
- API: http://localhost:8000
- Interactive Docs (Swagger): http://localhost:8000/docs
- Alternative Docs (ReDoc): http://localhost:8000/redoc
# Format code (inside container)
make format
# Type checking (inside container)
make mypy
# Run pre-commit hooks
make pre-commitCommon commands (use with docker exec or directly):
# Create a new migration
make alembic-revision
# Apply all pending migrations
make alembic-db-upgrade
# Rollback one migration (inside container)
alembic downgrade -1
# Show current migration version (inside container)
alembic current
# Show migration history (inside container)
alembic historyContributions are welcome! Please follow the existing architecture patterns and ensure all tests pass.
This project is licensed under the MIT License - see the LICENSE file for details.
Lotfi Ben Othman Linkedin: https://www.linkedin.com/in/lotfi-b-17a86681/