# luongnguyenminhan/fastapibase architecture

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

- Interactive diagram: https://gitdiagram.com/luongnguyenminhan/fastapibase
- Repository: https://github.com/luongnguyenminhan/fastapibase

## Overview

##### Project Purpose and Type
- It’s a backend API built using FastAPI, designed for scalability through modular organization and API versioning.
- The application emphasizes clear separation between API layers (controller endpoints), business logic (services), data access (repositories and unit of work), and database models.
- Docker support hints at containerized deployment with Docker Compose ensuring a consistent development and production environment.

##### File Structure and Architectural Components
- The “backend” directory contains the heart of the project:
- Controllers (or API endpoints) are organized into versioned directories (v1 and v2) – indicating API versioning to manage breaking changes or feature differences.
- The “services” directory implements business logic, further subdivided into core service functionality and utilities.
- The “repositories” folder abstracts data access logic, interfacing with the db models defined in “db/models”.
- The “schemas” directory defines data validation/input/output structures – split into business models and view models.
- The “unit_of_work” module ensures clean transaction management and consistency when interacting with data.
- Configuration files (e.g., .env.example and Dockerfile) indicate environment-specific settings and containerization.
- The “frontend” is present but minimal, suggesting that the main emphasis is on the backend API.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Global Entities
    Client["Client / External Consumer"]:::frontend
    Frontend["Frontend Placeholder"]:::frontend

    %% API Layer
    subgraph "API Layer"
        APIv1["API Controller (v1)"]:::api
        APIv2["API Controller (v2)"]:::api
        Schemas["Schemas (Data Validation & Serialization)"]:::schema
    end

    %% Service Layer
    subgraph "Service Layer"
        BusinessLogic["Business Logic (Services)"]:::service
        ServiceUtils["Service Utilities"]:::service
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        UnitOfWork["Unit of Work (Transaction Management)"]:::repository
        Repository["Repositories (Data Access)"]:::repository
        DBModels["Database Models"]:::repository
    end

    %% Infrastructure
    subgraph "Infrastructure"
        Infra["Docker & Env Config"]:::infra
    end

    %% Connections - Client and Frontend
    Client -->|"sends_request"| APIv1
    Client -->|"sends_request"| APIv2
    Frontend -->|"minimal_interaction"| APIv1
    Frontend -->|"minimal_interaction"| APIv2

    %% Controller to Schema and Service Layer
    APIv1 -->|"validates_with"| Schemas
    APIv2 -->|"validates_with"| Schemas
    APIv1 -->|"delegates_to"| BusinessLogic
    APIv2 -->|"delegates_to"| BusinessLogic

    %% Service Layer internal connection
    BusinessLogic -->|"utilizes"| ServiceUtils

    %% Service Layer to Data Access Layer
    BusinessLogic -->|"initiates_transaction"| UnitOfWork
    BusinessLogic -->|"calls_repositories"| Repository

    %% Data flow within Data Access
    UnitOfWork -->|"manages"| Repository
    Repository -->|"interacts_with"| DBModels

    %% Infrastructure supports backend layers
    Infra -->|"configures"| APIv1
    Infra -->|"configures"| APIv2
    Infra -->|"configures"| BusinessLogic
    Infra -->|"configures"| Repository

    %% Click Events
    click APIv1 "https://github.com/luongnguyenminhan/fastapibase/tree/main/backend/app/controllers/v1"
    click APIv2 "https://github.com/luongnguyenminhan/fastapibase/tree/main/backend/app/controllers/v2"
    click BusinessLogic "https://github.com/luongnguyenminhan/fastapibase/tree/main/backend/app/services/services"
    click ServiceUtils "https://github.com/luongnguyenminhan/fastapibase/blob/main/backend/app/services/utils/example_core.py"
    click Repository "https://github.com/luongnguyenminhan/fastapibase/tree/main/backend/app/repositories"
    click DBModels "https://github.com/luongnguyenminhan/fastapibase/tree/main/backend/app/db/models"
    click Schemas "https://github.com/luongnguyenminhan/fastapibase/tree/main/backend/app/schemas"
    click UnitOfWork "https://github.com/luongnguyenminhan/fastapibase/blob/main/backend/app/unit_of_work/unit_of_work.py"
    click Infra "https://github.com/luongnguyenminhan/fastapibase/tree/main/backend/Dockerfile"
    click Frontend "https://github.com/luongnguyenminhan/fastapibase/tree/main/frontend"

    %% Styles
    classDef api fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef service fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef repository fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef frontend fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef schema fill:#FFA500,stroke:#000,stroke-width:2px;
```
