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.

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

• 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

┌─────────────────────────────────────────┐
│   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         │
└─────────────────────────────────────────┘

• ✅ 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.

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

• 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

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

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

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

• 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.

# 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"

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

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.

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

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