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

bash

# 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

bash

# 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

python

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

bash

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

create_module.py

Generate new independent module:

bash

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

create_endpoint.py

Add endpoint to existing module:

bash

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

create_model.py

Create SQLAlchemy model + Alembic migration:

bash

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

validate_structure.py

Check project compliance:

bash

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.

fastapi-enterprise

NPX Install

Tags

SKILL.md Content

FastAPI Enterprise Development - Modular Architecture

Quick Start

Initialize Project

Create Independent Module

Minimal Modular App

Core Capabilities

1. Modular Architecture ⭐

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

3. Flexible Caching ⭐

4. Structured Logging (structlog)

5. Type-Safe Configuration

6. Async Database (SQLAlchemy 2.0)

7. Per-Module Migrations (Alembic)

8. Central HTTP Client (httpx)

9. Observability

10. Authentication (Conditional)

Automation Scripts

init_project.py

create_module.py

create_endpoint.py

create_model.py

validate_structure.py

Module Independence Rules

✅ DO:

❌ DON'T:

Resources

Reference Documentation

Automation Scripts

Examples

License