# rannysweis/fast-api-docker-poetry architecture

> Architecture diagram of the GitHub repository rannysweis/fast-api-docker-poetry, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rannysweis/fast-api-docker-poetry
- Repository: https://github.com/rannysweis/fast-api-docker-poetry

## Overview

##### Main Components
- API Layer: Represented by the controllers directory (order_controller, system_controller, and test_controller) which handle incoming HTTP requests.
- Service Layer: The services directory, e.g., order_service, that contains business logic and data transformation.
- Repository Layer: The repository folder that encapsulates database queries (order_repository, base_repository).
- Data Models: The models folder holds ORM and Pydantic models (order, address, base, pageable) crucial for data representation and persistence.
- Configuration & Utility: The config directory (settings, exception_config) and utils (db_session) handle app configuration, exception handling, and database session management.
- Bootstrapping: The main.py file that initializes the application and ties together exception handling and dependency injection (using decorators such as @cbv).
- Database Migrations: The migrations directory with Alembic scripts signifies database evolution and versioning.
- Testing: The tests directory, especially its integrations subfolder for API route tests.

- Containers & Orchestration: Include elements for Docker and Docker Compose that encapsulate the application environment.
- Dependency Management & Build: Note that Poetry is the primary dependency manager.
- Environment/Configuration Files: Represent additional files like .env, docker-compose.yml, and Dockerfile that are part of the deployment configuration.
- Tracing: A special component for Jaeger tracing (as mentioned under Quick Start) to monitor distributed traces.

##### Relationships and Interactions
- The API Layer (Controllers) receives HTTP requests and hands them over to the Service Layer.
- The Service Layer applies business logic then invokes the Repository Layer to perform database operations.
- The Repository interacts with the Database via ORM (managed through models) and sessions (using utilities like db_session).
- Configuration components (settings, exception handling) are used by all layers where needed.
- Migrations ensure that the database schema remains in sync with changes in the data models.
- Testing interacts with the API layer (using TestClient) to simulate real API calls.
- Docker and Docker Compose encapsulate these components in a containerized environment with appropriate orchestration.

##### Architectural Patterns
- Layered Architecture: Each folder (controllers, services, repository, models) corresponds to a distinct layer, promoting separation of concerns.
- Dependency Injection: Usage of decorators such as @cbv to initialize shared dependencies.
- Exception Handling: Custom exception configuration to manage HTTP errors centrally.
- Modular Design: The structure allows each layer to be updated independently, ensuring better maintainability.

- Main Application Container:
- FastAPI application (main.py) that aggregates Controllers, Config, and Exception Handlers.
- Controllers Component:
- Controller (order, system, test) plus a note on how they invoke services.
- Service Component:
- OrderService and note its role in handling business logic.
- Repository Component:
- OrderRepository’s role in abstracting database queries.
- Models Component:
- Order, address, and base models along with their role (ORM & Pydantic).
- Configuration & Utilities:
- Settings and DB session utility configurations.
- Database Migration:
- Alembic migrations directory.
- Testing:
- Integration tests illustrating testing the API endpoints.
- Docker Ecosystem:
- Dockerfile, docker-compose.yml, and associated scripts.
- Observability:
- Jaeger tracing as an external monitoring tool (if needed).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Container
    subgraph "Application Container"
        MAIN["main.py"]:::entry
        CONFIG["Configuration (settings, exception)"]:::config
        DBSESSION["DB Session Utility"]:::config
        CONTROLLERS["Controllers (order, system, test)"]:::api
        SERVICES["Order Service"]:::service
        REPOSITORIES["Repositories (base, order)"]:::repository
        MODELS["Models (order, address, base, pageable)"]:::models
    end

    %% Supporting Components
    subgraph "Supporting Components"
        MIGRATIONS["Migrations (Alembic)"]:::external
        TESTS["Integration Tests"]:::tests
        DEPENDENCY["Dependency Management (pyproject.toml)"]:::external
        JAEGER["Jaeger Tracing"]:::external
    end

    %% Docker Ecosystem
    subgraph "Docker Ecosystem"
        DOCKERFILE["Dockerfile"]:::container
        DOCKERCOMPOSE["docker-compose.yml"]:::container
        DOCKERCOMPOSE_LOCAL["docker-compose.local.yml"]:::container
    end

    %% Connections within Application Container
    MAIN -->|"init"| CONTROLLERS
    MAIN -->|"load"| CONFIG
    CONFIG -->|"provides"| DBSESSION
    CONTROLLERS -->|"calls"| SERVICES
    SERVICES -->|"invokes"| REPOSITORIES
    REPOSITORIES -->|"queries"| MODELS
    REPOSITORIES -->|"uses"| DBSESSION

    %% Connections with Supporting Components
    MIGRATIONS -->|"syncs"| MODELS
    TESTS -->|"tests"| CONTROLLERS
    DEPENDENCY -->|"configures"| MAIN
    JAEGER ---|"observes"| MAIN

    %% Connections with Docker Ecosystem
    DOCKERFILE --- MAIN
    DOCKERCOMPOSE --- MAIN
    DOCKERCOMPOSE_LOCAL --- MAIN
    MIGRATIONS --- DOCKERCOMPOSE

    %% Click Events
    click MAIN "https://github.com/rannysweis/fast-api-docker-poetry/blob/master/app/main.py"
    click CONFIG "https://github.com/rannysweis/fast-api-docker-poetry/tree/master/app/config"
    click DBSESSION "https://github.com/rannysweis/fast-api-docker-poetry/blob/master/app/utils/db_session.py"
    click CONTROLLERS "https://github.com/rannysweis/fast-api-docker-poetry/tree/master/app/controllers"
    click SERVICES "https://github.com/rannysweis/fast-api-docker-poetry/blob/master/app/services/order_service.py"
    click REPOSITORIES "https://github.com/rannysweis/fast-api-docker-poetry/tree/master/app/repository"
    click MODELS "https://github.com/rannysweis/fast-api-docker-poetry/tree/master/app/models"
    click MIGRATIONS "https://github.com/rannysweis/fast-api-docker-poetry/tree/master/migrations"
    click TESTS "https://github.com/rannysweis/fast-api-docker-poetry/tree/master/tests/integrations"
    click DOCKERFILE "https://github.com/rannysweis/fast-api-docker-poetry/tree/master/Dockerfile"
    click DOCKERCOMPOSE "https://github.com/rannysweis/fast-api-docker-poetry/blob/master/docker-compose.yml"
    click DOCKERCOMPOSE_LOCAL "https://github.com/rannysweis/fast-api-docker-poetry/blob/master/docker-compose.local.yml"
    click DEPENDENCY "https://github.com/rannysweis/fast-api-docker-poetry/blob/master/pyproject.toml"

    %% Style Definitions
    classDef entry fill:#ead1dc,stroke:#333,stroke-width:2px;
    classDef api fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef service fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef repository fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef models fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef config fill:#f8d7da,stroke:#333,stroke-width:2px;
    classDef tests fill:#d1c4e9,stroke:#333,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:2px;
    classDef container fill:#d9edf7,stroke:#333,stroke-width:2px;
```
