# mannam95/fastapi-poc architecture

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

- Interactive diagram: https://gitdiagram.com/mannam95/fastapi-poc
- Repository: https://github.com/mannam95/fastapi-poc

## Overview

##### Project type and purpose
- This is a backend API service built with FastAPI and async SQLAlchemy following Domain-Driven Design (DDD) principles.
- The primary purpose is to expose CRUD endpoints for domains like user, department, location, process, resource, and role, backed by a PostgreSQL database.
- It includes centralized logging (Loguru), exception handling, Docker-Compose orchestration, a test suite (pytest), and benchmarking (Locust).

##### File structure
- Top level:
- app/: the main Python package
- docker/: Dockerfiles and compose files for development/test/prod
- docs/: markdown docs on architecture, Docker, testing, etc.
- locust/: load-testing scripts
- prometheus/: monitoring configuration
- tests/: unit and integration tests
- app/ layers:
- app/api/router.py – the single FastAPI router mounting domain routers
- app/core/ – configuration and database session initialization
- app/domains/ – each subfolder is a DDD “module” with its own router, schemas, model, service, and dependency definitions
- app/utils/ – logging middleware/service, exception definitions, DB-init scripts, SQL scripts
- app/main.py – FastAPI app instantiation, middleware registration
- Config files: .env.example, pyproject.toml, requirements.txt, Makefile, docker-compose.yml

##### README for additional insights
- Confirms use of FastAPI + async SQLAlchemy, PostgreSQL via asyncpg, DDD, dependency injection, Loguru, centralized exception handling.
- Docker-Compose for orchestration, Locust for benchmarking, Flake8/Mypy/Black/isort for quality.
- Future integration: Prometheus/Grafana, Alembic, Redis, WebSockets.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation/API Layer
    subgraph "API Layer"
        FAP("FastAPI App"):::frontend
        Router("API Router"):::frontend
    end

    %% Domain Routers
    subgraph "Domain Routers"
        UR("User Router"):::frontend
        DR("Department Router"):::frontend
        LR("Location Router"):::frontend
        PR("Process Router"):::frontend
        RR("Resource Router"):::frontend
        ROR("Role Router"):::frontend
    end

    %% Service Layer
    subgraph "Service Layer"
        US("User Service"):::domain
        DS("Department Service"):::domain
        LS("Location Service"):::domain
        PS("Process Service"):::domain
        RS("Resource Service"):::domain
        ROS("Role Service"):::domain
        BS("Base Service"):::domain
        ES("Exception Handling Service"):::domain
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        UM("User Model"):::persistence
        DM("Department Model"):::persistence
        LM("Location Model"):::persistence
        PM("Process Model"):::persistence
        RM("Resource Model"):::persistence
        ROM("Role Model"):::persistence
        DB("PostgreSQL Database"):::persistence
    end

    %% Infrastructure & External
    subgraph "Infrastructure & External"
        LOG("Loguru Logging"):::infra
        EXM("Exception Middleware"):::infra
        DI("Dependency Injection"):::infra
        DC("Docker Compose"):::infra
        PYT("pytest Testing"):::external
        LOC("Locust Benchmarking"):::external
        PRO("Prometheus Monitoring"):::external
    end

    %% Flow
    HTTP["HTTP Client"]:::external -->|"JSON/HTTP"| FAP
    FAP -->|mounts| Router
    Router -->|routes to| UR
    Router -->|routes to| DR
    Router -->|routes to| LR
    Router -->|routes to| PR
    Router -->|routes to| RR
    Router -->|routes to| ROR

    UR -->|calls| US
    DR -->|calls| DS
    LR -->|calls| LS
    PR -->|calls| PS
    RR -->|calls| RS
    ROR -->|calls| ROS

    US -->|inherits| BS
    DS -->|inherits| BS
    LS -->|inherits| BS
    PS -->|inherits| BS
    RS -->|inherits| BS
    ROS -->|inherits| BS
    US -->|uses| ES
    DS -->|uses| ES
    LS -->|uses| ES
    PS -->|uses| ES
    RS -->|uses| ES
    ROS -->|uses| ES

    US -->|queries| UM
    DS -->|queries| DM
    LS -->|queries| LM
    PS -->|queries| PM
    RS -->|queries| RM
    ROS -->|queries| ROM

    UM -->|SQL via async ORM| DB
    DM -->|SQL via async ORM| DB
    LM -->|SQL via async ORM| DB
    PM -->|SQL via async ORM| DB
    RM -->|SQL via async ORM| DB
    ROM -->|SQL via async ORM| DB

    EXM -->|applies to| FAP
    LOG -->|integrated in| FAP
    DI -->|injects into| Router

    DC -->|orchestrates| FAP
    DC -->|orchestrates| DB

    LOC -->|sends load to| FAP
    PRO -->|scrapes metrics| FAP
    PYT -->|tests| Router

    %% Click Events
    click FAP "https://github.com/mannam95/fastapi-poc/blob/main/app/main.py"
    click Router "https://github.com/mannam95/fastapi-poc/blob/main/app/api/router.py"
    click UR "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/user/user_router.py"
    click DR "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/department/department_router.py"
    click LR "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/location/location_router.py"
    click PR "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/process/process_router.py"
    click RR "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/resource/resource_router.py"
    click ROR "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/role/role_router.py"
    click US "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/user/user_service.py"
    click DS "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/department/department_service.py"
    click LS "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/location/location_service.py"
    click PS "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/process/process_service.py"
    click RS "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/resource/resource_service.py"
    click ROS "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/role/role_service.py"
    click BS "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/shared/service/base_service.py"
    click ES "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/shared/service/exception_handling_service.py"
    click UM "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/user/user_model.py"
    click DM "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/department/department_model.py"
    click LM "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/location/location_model.py"
    click PM "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/process/process_model.py"
    click RM "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/resource/resource_model.py"
    click ROM "https://github.com/mannam95/fastapi-poc/blob/main/app/domains/role/role_model.py"
    click LOG "https://github.com/mannam95/fastapi-poc/blob/main/app/utils/logging_service.py"
    click EXM "https://github.com/mannam95/fastapi-poc/blob/main/app/utils/logging_middleware.py"
    click DC "https://github.com/mannam95/fastapi-poc/blob/main/docker/docker-compose.yml"
    click PYT "https://github.com/mannam95/fastapi-poc/blob/main/tests/conftest.py"
    click LOC "https://github.com/mannam95/fastapi-poc/blob/main/locust/locustfile.py"
    click PRO "https://github.com/mannam95/fastapi-poc/blob/main/prometheus/prometheus.yml"

    %% Styles
    classDef frontend fill:#D0E6FA,stroke:#1E70BF,color:#0B3D91;
    classDef domain fill:#E6F4EA,stroke:#2E8B57,color:#006400;
    classDef persistence fill:#FFE8CC,stroke:#CC8400,color:#8B4500;
    classDef infra fill:#FDE2E1,stroke:#D64541,color:#A31F34;
    classDef external fill:#F0F0F0,stroke:#B0B0B0,color:#707070;
```
