FastAPI Clean Architecture Blueprint

A comprehensive, production-ready blueprint for implementing Clean Architecture in FastAPI projects. This template provides a modular, scalable foundation for building modern web applications following SOLID principles and separation of concerns.

📋 Quick Start

1. Clone or copy this blueprint to your new project
2. Update project metadata in pyproject.toml and config/settings.py
3. Install dependencies: pip install -r requirements.txt
4. Run the application: uvicorn src.main:app --reload
5. Run tests: pytest

📚 Documentation

• Architecture Overview - High-level design and Clean Architecture principles
• Project Structure - Detailed folder organization and purpose
• Development Guide - How to extend and add features
• Testing Strategy - Unit and integration testing approach

🏗️ Architecture Layers

┌─────────────────────────────────────────┐
│   Presentation Layer (API)              │
│   - FastAPI routes, dependencies        │
│   - Request/response schemas            │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│   Application Layer                     │
│   - Use cases, application services     │
│   - Business orchestration              │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│   Domain Layer (Core Business Logic)    │
│   - Entities, value objects             │
│   - Domain rules & invariants           │
└──────────────┬──────────────────────────┘
               │
┌──────────────▼──────────────────────────┐
│   Infrastructure Layer                  │
│   - Database, repositories              │
│   - External services, adapters         │
└─────────────────────────────────────────┘

🚀 Key Features

• ✅ Clean Architecture - Well-separated concerns with testable, maintainable code
• ✅ Dependency Injection - Using FastAPI's Depends and manual injection
• ✅ Repository Pattern - Abstract data access with multiple implementation options
• ✅ Environment Configuration - Support for .env files and environment-specific settings
• ✅ Error Handling - Custom exceptions and centralized error responses
• ✅ Validation - Pydantic schemas for request/response validation
• ✅ Logging - Structured logging with Python's logging module
• ✅ Testing - Comprehensive unit and integration test examples
• ✅ Database Agnostic - Easily switch between SQLAlchemy, MongoDB, etc.

📁 Directory Structure

FastAPIBluePrint/
├── src/
│   ├── domain/              # Core business logic (entities, interfaces)
│   ├── application/         # Use cases and application services
│   ├── infrastructure/      # Database, external services, repositories
│   ├── presentation/        # FastAPI routes, schemas, dependencies
│   ├── config/              # Configuration management
│   └── main.py              # Application entry point
├── tests/
│   ├── unit/                # Unit tests for use cases
│   ├── integration/         # Integration tests for adapters
│   └── conftest.py          # Pytest fixtures and configuration
├── docs/                    # Documentation files
├── config/                  # Runtime configuration
├── pyproject.toml           # Project metadata and dependencies
├── requirements.txt         # Python dependencies
├── .env.example             # Environment variables template
└── pytest.ini               # Pytest configuration

🔧 Technology Stack

• Framework: FastAPI 0.104+
• Python: 3.10+
• Database: SQLAlchemy ORM (adapter pattern allows alternatives)
• Validation: Pydantic v2
• Testing: pytest, pytest-asyncio
• Logging: Python's built-in logging
• Configuration: python-dotenv, Pydantic Settings

💡 Use Case Examples

This blueprint is suitable for:

• CRUD Applications - User management, content management systems
• Domain-driven Design Projects - Complex business logic with rich domain models
• Microservices - Isolated, independently deployable services
• REST APIs - Clean separation between business logic and API layer
• Event-driven Systems - Extensible architecture for event handling

🎯 Adapting for Different Scales

Small Projects (1-2 developers)

• Keep all use cases in a single file per feature
• Simplify repository implementations
• Minimal configuration complexity

Medium Projects (3-5 developers)

• One use case per file
• Multiple repository implementations
• Enhanced error handling and logging

Large Projects (6+ developers)

• Feature-based organization within layers
• Multiple database backends
• Event-driven architecture, messaging queues
• Comprehensive testing and CI/CD

See Development Guide for detailed scaling strategies.

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src

# Run specific test file
pytest tests/unit/test_example.py

# Run tests matching pattern
pytest -k "test_user"

📖 Learning Path

1. Start with Architecture Overview
2. Review Project Structure
3. Examine skeleton code in src/ directory
4. Read Development Guide for adding features
5. Study test examples in tests/ directory
6. Refer to Testing Strategy

🤝 Contributing & Extending

To add a new feature:

1. Create entities in domain/entities/
2. Define repository interfaces in domain/repositories/
3. Implement use cases in application/use_cases/
4. Add repository implementations in infrastructure/repositories/
5. Create FastAPI routers in presentation/routers/
6. Add tests in tests/unit/ and tests/integration/

See Development Guide for detailed examples.

📝 License

This blueprint is provided as-is for educational and commercial use.

---

Last Updated: December 2025
Version: 1.0.0
Python: 3.10+