# neonkid/fastapi-ddd-example architecture

> Architecture diagram of the GitHub repository neonkid/fastapi-ddd-example, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/neonkid/fastapi-ddd-example
- Repository: https://github.com/neonkid/fastapi-ddd-example

## Overview

##### Main Components

a) Core Layers:
- Domain Layer (modules/*/domain)
- Application Layer (modules/*/usecase)
- Infrastructure Layer (modules/*/infrastructure)
- Presentation Layer (FastAPI routes)

b) Cross-Cutting Components:
- Event System
- Dependency Injection Container
- Common Protocols
- Error Handling

##### Architectural Patterns to Highlight

- CQRS (Command Query Responsibility Segregation)
- Event-Driven Architecture
- Repository Pattern
- Unit of Work Pattern
- Domain Events

##### Detailed Component Breakdown

API Layer:
**┌─────────────────────────────────────────┐**
- FastAPI Routes             │
- ┘

Use Cases Layer:
**┌─────────────────────────────────────────┐**
- Command Use Cases    │    Query Use Cases│
- (State Modification) │    (Data Fetch)   │
- ┘

Domain Layer:
**┌─────────────────────────────────────────┐**
- Book Aggregate    │  Author Aggregate │
- Domain Model    │  - Domain Model   │
- Value Objects   │  - Value Objects  │
- ┘

Infrastructure Layer:
**┌─────────────────────────────────────────┐**
- Persistence         │      Query        │
- Repositories     │   - DTOs          │
- Unit of Work     │   - Repositories  │
- ┘

##### Event System Flow

**Domain Event → Event Dispatcher → Event Handlers**

##### Important Relationships

- One-way dependencies pointing downward (following clean architecture)
- Event flow between bounded contexts
- CQRS separation between read and write operations
- Dependency injection flow

##### Additional Elements

A separate section showing:
- Snowflake ID generation
- Database schema (as shown in README)
- Protocol interfaces
- Error handling flow

##### Implementation Details

- FastAPI dependency injection system
- SQLAlchemy classical mapping
- Event processing flow
- Repository pattern implementation
- Unit of Work transaction boundaries

##### Notes

Important notes about:
- Explicit dependency injection
- Transaction boundaries
- Event handling asynchronous nature
- CQRS implementation details

Remember to keep the abstraction level high enough to be understandable but detailed enough to show the important architectural decisions made in the project.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph API
        Routes["FastAPI Routes"]:::api
        ErrorHandler["Error Handler"]:::api
        APIResponse["API Response Handler"]:::api
    end

    subgraph UseCases
        direction TB
        CommandUseCases["Command Use Cases"]:::usecase
        QueryUseCases["Query Use Cases"]:::usecase
        
        subgraph BookUseCases
            NewBookUseCase["New Book Use Case"]:::usecase
        end
        
        subgraph AuthorUseCases
            NewAuthorUseCase["New Author Use Case"]:::usecase
        end
    end

    subgraph Domain
        direction TB
        subgraph BookDomain
            BookAggregate["Book Aggregate"]:::domain
            BookValueObjects["Book Value Objects"]:::domain
        end
        
        subgraph AuthorDomain
            AuthorAggregate["Author Aggregate"]:::domain
            AuthorValueObjects["Author Value Objects"]:::domain
        end
    end

    subgraph Infrastructure
        direction TB
        subgraph Persistence
            BookRepo["Book Repository"]:::infra
            AuthorRepo["Author Repository"]:::infra
            BookUoW["Book Unit of Work"]:::infra
            AuthorUoW["Author Unit of Work"]:::infra
        end
        
        subgraph Query
            BookQuery["Book Query Repository"]:::infra
            AuthorQuery["Author Query Repository"]:::infra
        end
    end

    subgraph EventSystem
        EventDispatcher["Event Dispatcher"]:::event
        EventHandler["Event Handler"]:::event
        EventMiddleware["Event Middleware"]:::event
    end

    subgraph CrossCutting
        DIContainer["Dependency Injection Container"]:::cross
        Protocols["Common Protocols"]:::cross
        SnowflakeID["Snowflake ID Generator"]:::cross
    end

    %% Relationships
    Routes --> CommandUseCases
    Routes --> QueryUseCases
    Routes --> ErrorHandler
    Routes --> APIResponse
    
    CommandUseCases --> Domain
    QueryUseCases --> Query
    
    Domain --> EventDispatcher
    EventDispatcher --> EventHandler
    EventMiddleware --> EventDispatcher
    
    BookAggregate --> BookRepo
    AuthorAggregate --> AuthorRepo
    
    BookRepo --> BookUoW
    AuthorRepo --> AuthorUoW
    
    DIContainer --> Routes
    DIContainer --> UseCases
    DIContainer --> Infrastructure

    %% Click Events
    click Routes "https://github.com/NEONKID/fastapi-ddd-example/blob/main/core/fastapi/routes.py"
    click ErrorHandler "https://github.com/NEONKID/fastapi-ddd-example/blob/main/core/fastapi/error.py"
    click APIResponse "https://github.com/NEONKID/fastapi-ddd-example/blob/main/core/fastapi/responses.py"
    click BookDomain "https://github.com/NEONKID/fastapi-ddd-example/tree/main/modules/book/domain/"
    click AuthorDomain "https://github.com/NEONKID/fastapi-ddd-example/tree/main/modules/author/domain/"
    click NewBookUseCase "https://github.com/NEONKID/fastapi-ddd-example/tree/main/modules/book/usecase/newBook/"
    click NewAuthorUseCase "https://github.com/NEONKID/fastapi-ddd-example/tree/main/modules/author/usecase/newAuthor/"
    click BookRepo "https://github.com/NEONKID/fastapi-ddd-example/blob/main/persistence/book/repository.py"
    click AuthorRepo "https://github.com/NEONKID/fastapi-ddd-example/blob/main/persistence/author/repository.py"
    click BookUoW "https://github.com/NEONKID/fastapi-ddd-example/blob/main/modules/book/infrastructure/persistence/uow.py"
    click AuthorUoW "https://github.com/NEONKID/fastapi-ddd-example/blob/main/modules/author/infrastructure/persistence/uow.py"
    click EventDispatcher "https://github.com/NEONKID/fastapi-ddd-example/blob/main/core/fastapi/event/dispatcher.py"
    click EventHandler "https://github.com/NEONKID/fastapi-ddd-example/blob/main/core/fastapi/event/handler.py"
    click EventMiddleware "https://github.com/NEONKID/fastapi-ddd-example/blob/main/core/fastapi/event/middleware.py"
    click DIContainer "https://github.com/NEONKID/fastapi-ddd-example/blob/main/container.py"
    click Protocols "https://github.com/NEONKID/fastapi-ddd-example/tree/main/common/protocols/"
    click SnowflakeID "https://github.com/NEONKID/fastapi-ddd-example/blob/main/core/snowflake.py"

    %% Styles
    classDef api fill:#2196F3,stroke:#1565C0,color:white
    classDef usecase fill:#4CAF50,stroke:#2E7D32,color:white
    classDef domain fill:#FFC107,stroke:#FFA000,color:black
    classDef infra fill:#FF5722,stroke:#E64A19,color:white
    classDef event fill:#9C27B0,stroke:#7B1FA2,color:white
    classDef cross fill:#795548,stroke:#5D4037,color:white
```
