FastAPI Enterprise Development - Modular Architecture

Enterprise-grade FastAPI with modular architecture: each business domain is an independent module with own database tables, cache namespace, routes, and migrations. Modern Python tooling (UV + pyproject.toml) for fast dependency management.

Quick Start

Initialize Project

# Create modular FastAPI project with UV
python scripts/init_project.py --name my_api --auth keycloak --with-example-module

# Result:
# my_api/                    ← Project name subdirectory
# ├── src/
# │   ├── app.py             ← Main application
# │   ├── core/              ← Shared infrastructure (logging, DB, cache, module loader)
# │   ├── middleware/        ← Conversation tracking, auth
# │   └── routes/            ← Core routes (health, metrics)
# ├── modules/               ← Independent modules
# │   └── users/             ← Example: own routes, models, cache, migrations
# ├── pyproject.toml         ← UV configuration
# ├── config/                ← YAML configurations
# └── scripts/               ← Automation (create_module.py)

# Install and run
cd my_api
uv sync                      # Install dependencies (10-100x faster than pip)
cp .env.example .env
uv run uvicorn src.app:app --reload

Create Independent Module

# Generate new module with complete structure
uv run python scripts/create_module.py --name orders

# Auto-creates:
# modules/orders/
# ├── __init__.py          ← Router export (auto-discovered)
# ├── routes/              ← /api/v1/orders endpoints
# ├── models/              ← SQLAlchemy models (own tables)
# ├── schemas/             ← Pydantic validation
# ├── services/            ← Business logic
# ├── cache/               ← Module-specific cache (orders:* prefix)
# ├── enums/               ← Module-specific enums
# └── alembic/             ← Module-specific migrations

Minimal Modular App

# src/app.py
from fastapi import FastAPI
from src.core.config import settings
from src.core.logging import configure_logging
from src.core.cache import cache_manager
from src.core.module_loader import discover_modules
from src.middleware.conversation_middleware import ConversationMiddleware

# Configure logging (JSON/colored)
configure_logging(environment=settings.ENVIRONMENT)

app = FastAPI(title=settings.PROJECT_NAME)
app.add_middleware(ConversationMiddleware)  # UUID tracking

@app.on_event("startup")
async def startup():
    await cache_manager.connect()  # Redis or memory
    discover_modules(app)           # Auto-register all modules

@app.get("/")
async def root():
    return {"message": "Welcome"}

Core Capabilities

1. Modular Architecture ⭐

• •Independent Modules: Each module owns DB tables, cache keys, routes
• •Auto-Discovery: Modules in modules/ automatically registered
• •Service-Layer Communication: Inter-module calls via services (no direct model imports)
• •Per-Module Migrations: Each module has own Alembic history
• •Enforced Boundaries: modules.users.services.UserService ✅ | from modules.users.models import User ❌

Module Patterns Guide

2. Modern Python Tooling (UV + pyproject.toml) ⭐

• •UV: 10-100x faster than pip, Rust-based package manager
• •pyproject.toml: PEP 518/621 standard, replaces requirements.txt
• •uv.lock: Reproducible builds across environments
• •Project Subdirectory: All files in my_api/ (clean workspace)
• •Export: uv export --format requirements-txt > requirements.txt when needed

Project Structure

3. Flexible Caching ⭐

• •Redis (production): Distributed, persistent cache
• •Memory (development): Zero dependencies, instant setup
• •Module Namespaces: users:123, orders:456 (no collisions)
• •Cache Decorators: @cached(prefix="products", ttl=1800)
• •Invalidation: Time-based (TTL), event-based (on update), pattern-based (users:*)

Cache Patterns

4. Structured Logging (structlog)

• •JSON (production): Structured logs for aggregation (ELK, Splunk)
• •Colored Console (development): Human-readable with syntax highlighting
• •Conversation ID: UUID in all logs from ConversationMiddleware
• •Request/Response: Automatic logging with duration, status code
• •External APIs: Conversation ID propagated to downstream services

Logging Patterns

5. Type-Safe Configuration

• •pydantic-settings: OS environment variables with type validation
• •YAML: config/development.yml and config/production.yml
• •Variable Substitution: ${DATABASE_PASSWORD} from environment
• •CONFIG_ENV Switcher: Toggle between dev/prod configs

Configuration Patterns

6. Async Database (SQLAlchemy 2.0)

• •Async: Full asyncio support with asyncpg driver
• •PostgreSQL-Optimized: JSONB, arrays, full-text search
• •Per-Module Tables: Each module creates own tables
• •Central Session: src/core/db.py session factory used by all modules and Alembic

Database Patterns

7. Per-Module Migrations (Alembic)

• •Independent Histories: modules/users/alembic/, modules/orders/alembic/
• •Async Template: Configured for async SQLAlchemy
• •Auto-Generation: alembic revision --autogenerate
• •Run All: python scripts/run_migrations.py --all

Alembic Setup

8. Central HTTP Client (httpx)

• •Async: Connection pooling, timeouts, retries
• •Conversation ID: Auto-propagated to X-Conversation-ID header
• •YAML Configs: Base URLs from config/*.yml
• •Request Logging: All external API calls logged

HTTPx Patterns

9. Observability

• •Conversation Tracking: UUID from header/cookie, appears in all logs
• •Prometheus Metrics: /metrics endpoint (request count, latency, errors)
• •OpenTelemetry (optional): Distributed tracing (Jaeger, Zipkin)
• •Health Check: /health with DB connectivity status

Observability Patterns

10. Authentication (Conditional)

AI MUST ASK: "Keycloak authentication (JWT from external IdP) or app-based RBAC (database-backed roles)?"

• •Keycloak: JWT validation, role extraction, Keycloak OpenID integration
• •App-based: Custom JWT, database roles/permissions, user management
• •Middleware: Token validation, request.state.current_user injection
• •Role Decorators: @requires_role("admin")

Authentication Patterns

Automation Scripts

init_project.py

Initialize complete project with modular structure:

python scripts/init_project.py --name my_api --auth keycloak --with-example-module

create_module.py

Generate new independent module:

uv run python scripts/create_module.py --name products

create_endpoint.py

Add endpoint to existing module:

uv run python scripts/create_endpoint.py --module users --service auth --method post --path login

create_model.py

Create SQLAlchemy model + Alembic migration:

uv run python scripts/create_model.py --module products --name Product

validate_structure.py

Check project compliance:

uv run python scripts/validate_structure.py

Module Independence Rules

✅ DO:

• •Service Layer Communication: from modules.users.services.user_service import UserService
• •Module Namespaces: users:cache:123, orders:cache:456
• •Own Tables: Each module creates own database tables
• •Own Migrations: Separate Alembic history per module

❌ DON'T:

• •Direct Model Imports: from modules.users.models.user import User (use service instead)
• •Shared Tables: No ForeignKey("users.id") across modules (store as regular int)
• •Cross-Module Cache: Don't access other module's cache directly

Clean Code Standards

Resources

Reference Documentation

• •Project Structure - Directory layout, UV setup
• •Module Patterns - Independent module development
• •Cache Patterns - Redis/memory caching strategies
• •Routing Patterns - Auto-discovery, module loader
• •Logging Patterns - Structlog configuration
• •Configuration Patterns - pydantic-settings, YAML
• •Database Patterns - Async SQLAlchemy, CRUD
• •Alembic Setup - Per-module migrations
• •HTTPx Patterns - Central HTTP client
• •Observability Patterns - Conversation tracking, metrics
• •Authentication Patterns - Keycloak vs app-based
• •Clean Code Standards - DDD, no duplication
• •Error Handling Workflow - Systematic debugging

Automation Scripts

• •scripts/init_project.py - Initialize complete project
• •scripts/create_module.py - Generate new module
• •scripts/create_endpoint.py - Add endpoint to module
• •scripts/create_model.py - Create model + migration
• •scripts/validate_structure.py - Check project compliance

Examples

• •Complete Usage Examples - 6 full examples (module creation, cache usage, auth, metrics, etc.)

License

MIT License - See LICENSE.txt for complete terms.