Functional Programming (🟡)

• Use Cases - Pure functions: async def login_user(request, deps) -> response
• Value Objects - Immutable data structures with validation: NamedTuple + factory functions
• Domain Events - Immutable event data: UserCreated(user_id, email) -> DomainEventValue
• DTOs - Pure data containers: LoginRequest(email, password) -> LoginRequestValue
• Service Composition - Function composition and partial application

# Pure function use case
async def login_user(request: LoginRequest, deps: Dependencies) -> LoginResponse:
    user = await deps.user_repository.find_by_email(email)
    session = user.authenticate(password)  # Entity method
    return LoginResponse(access_token=token.value)

# Immutable value object
class EmailValue(NamedTuple):
    value: str
    domain: str

def Email(email_string: str) -> EmailValue:
    # Validation + normalization
    return EmailValue(value=normalized, domain=domain)

Object-Oriented Programming (🔵)

• Domain Entities - Rich objects with identity and behavior
• Repository Interfaces - Abstract data access contracts

# Entity with identity and behavior
class User:
    def authenticate(self, password: Password) -> Session:
        if not self.password_hash.verify(password):
            raise ValueError("Invalid credentials")
        return Session.create_for_user(self.id, self.email, self.permissions)

This hybrid approach gives us immutability where it matters (value objects, use cases) and rich domain models where appropriate (entities with business logic).

🚀 Progressive Architecture

The project follows a phased approach to CQRS adoption:

1. Phase 1 ✅ - Clean Architecture foundation with DDD
2. Phase 2 ✅ - CQRS separation + FastAPI presentation layer + PostgreSQL persistence
3. Phase 3 - Redis caching layer for sub-10ms performance
4. Phase 4 - Full CQRS with event sourcing
5. Phase 5 - High availability and scaling
6. Phase 6 - Security, integration, and observability

📁 Project Structure

src/
├── heimdall/
│   ├── domain/          # Business rules & entities
│   │   ├── entities/    # User, Session (OOP)
│   │   ├── value_objects/  # Email, Password, Token (Functional)
│   │   ├── events/      # Domain events (Functional)
│   │   └── repositories/   # Abstract interfaces (OOP)
│   │       ├── read_repositories.py   # Read-optimized (CQRS)
│   │       └── write_repositories.py  # Write-optimized (CQRS)
│   ├── application/     # Use cases & orchestration
│   │   ├── commands/    # Write operations (CQRS - 1% traffic)
│   │   ├── queries/     # Read operations (CQRS - 99% traffic)
│   │   ├── cqrs.py      # Unified CQRS facade
│   │   ├── dto/         # Data Transfer Objects (Functional)
│   │   └── services/    # Function composition (Functional)
│   ├── infrastructure/ # External integrations
│   │   └── persistence/ # Data persistence layer
│   │       └── postgres/ # PostgreSQL implementation
│   │           ├── database.py        # Connection management
│   │           ├── dependencies.py    # PostgreSQL dependencies
│   │           ├── mappers.py         # Database ↔ domain mapping
│   │           ├── user_repository.py # User persistence
│   │           └── session_repository.py # Session persistence
│   └── presentation/    # Interface adapters
│       └── api/         # FastAPI application
│           ├── main.py      # FastAPI app configuration
│           ├── routes.py    # Authentication endpoints
│           ├── dependencies.py # Dynamic dependency injection
│           ├── schemas.py   # Pydantic request/response schemas
│           └── health.py    # Health check endpoints
└── tests/
    ├── unit/           # 87 tests - Domain & CQRS logic
    └── integration/    # 36 tests - Full-stack API testing
        ├── aux/               # Test infrastructure utilities
        │   ├── api_fixtures.py    # FastAPI fixtures (api_client) - pytest_plugins
        │   ├── api_helpers.py     # Functional API helpers (register_user, etc.)
        │   └── postgres_helpers.py # PostgreSQL utilities (connection, cleanup)
        └── usecases/          # Organized by CQRS patterns
            ├── commands/      # Write operation tests (1% traffic)
            └── queries/       # Read operation tests (99% traffic)

🧪 Testing (123 Total Tests)

Quick Commands (Makefile)

# Default: Run all test suites (requires PostgreSQL)
make test              # 123 tests in ~14s (unit + integration)

# Specific test suites
make test-unit         # 87 tests in ~5s (fast feedback)
make test-integration  # 36 tests in ~9s (API integration with PostgreSQL)
make test-postgres     # Alias for test-integration (PostgreSQL required)

# Development workflows
make quick             # Same as test-unit (fast development)
make workflow          # Full development pipeline
make ci-test           # Complete CI validation

Manual Commands

# Unit tests only
PYTHONPATH=src python -m pytest src/tests/unit/ -v

# Integration tests (requires PostgreSQL to be running)
docker-compose up -d postgres  # Start PostgreSQL container
PYTHONPATH=src python -m pytest src/tests/integration/ -v

Test Coverage

• 87 Unit Tests: Domain entities, CQRS commands/queries, value objects, events
• 36 Integration Tests: Full-stack API testing through FastAPI endpoints with PostgreSQL
  • Commands: Write operations (login, register) - 1% traffic (8 tests)
  • Queries: Read operations (token validation, health checks) - 99% traffic (28 tests)
  • PostgreSQL Required: Tests use PostgreSQL for realistic persistence validation
  • Clean Architecture: Separated fixtures, helpers, and PostgreSQL utilities
  • No conftest.py: Direct fixture loading via pytest_plugins for explicit control
• Total: 123 automated tests with comprehensive coverage

PostgreSQL Integration Testing

Integration tests require PostgreSQL to be running and use production-like persistence:

# Start PostgreSQL first (required)
docker-compose up -d postgres

# Run integration tests with PostgreSQL
make test-integration

Key Features:

• Database Isolation: Each test starts with a clean database state
• Real JWT Tokens: Proper token validation with database session lookup
• ACID Compliance: Tests verify database constraints and transactions
• Connection Verification: Tests verify PostgreSQL availability before running
• Clean Architecture: Separated fixtures (api_fixtures.py), helpers (api_helpers.py), PostgreSQL (postgres_helpers.py)
• No pytest warnings: File separation eliminates PytestAssertRewriteWarning
• External Container Management: Users manage PostgreSQL containers independently

📖 Documentation

For detailed architectural decisions and trade-offs, see Technical Assessment.

🎯 Design Principles

1. Optimize for the common case - Token validation is 99% of traffic
2. CQRS separation - Different models for reads vs writes
3. Pure functions over classes - Easier to test, reason about, and scale
4. Immutable value objects - Thread-safe by default
5. Explicit dependencies - No hidden state or magic
6. Progressive complexity - Start simple, evolve as needed
7. API-first design - Complete FastAPI integration with type safety
8. Test-driven architecture - 133 tests covering all layers

🔄 CQRS Implementation (Phase 2 Complete)

Architecture Overview

Complete command/query separation with FastAPI presentation layer, optimized for the 100:1 read/write ratio typical in authentication systems.

FastAPI Integration

# FastAPI routes with dependency injection
@router.post("/auth/login")
async def login(
    request: LoginRequestSchema,
    auth_functions: dict = Depends(get_auth_functions)
) -> LoginResponseSchema:
    response = await auth_functions["login"](request.to_domain())
    return LoginResponseSchema.from_domain(response)

@router.post("/auth/validate")
async def validate_token(
    request: ValidateTokenRequestSchema,
    auth_functions: dict = Depends(get_auth_functions)
) -> ValidateTokenResponseSchema:
    response = await auth_functions["validate"](request.token)
    return ValidateTokenResponseSchema.from_domain(response)

Functional CQRS with Curried Functions

# Create optimized dependencies for commands and queries
command_deps = CommandDependencies(user_repo, session_repo, token_service, event_bus)
query_deps = QueryDependencies(cached_session_repo, token_service)  # Minimal deps

# Curry CQRS functions with dependencies baked in
auth_functions = curry_cqrs_functions(command_deps, query_deps)

# Use the curried functions - dependencies already applied
await auth_functions["login"](request)      # Write operation (1% traffic)
await auth_functions["validate"](token)     # Read operation (99% traffic)

Command Side (Write Operations - 1% of traffic)

• Commands: login_user_command, register_user_command, logout_user_command
• Focus: Data consistency, domain events, full business logic
• Dependencies: Write repositories, event bus, full domain services
• API Endpoints: /auth/login, /auth/register, /auth/logout

Query Side (Read Operations - 99% of traffic)

• **Queri