# ashbhat/boilerplate_fastapi architecture

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

- Interactive diagram: https://gitdiagram.com/ashbhat/boilerplate_fastapi
- Repository: https://github.com/ashbhat/boilerplate_fastapi

## Overview

##### Project Type and Purpose
- This is a FastAPI boilerplate/project template for building a backend HTTP API.
- It uses Uvicorn to serve the application, SQLAlchemy + Alembic for DB migrations, and Postgres as the persistence layer.
- Its purpose is to let a developer clone the template, define new “sample”-style modules, run migrations, and have a working API immediately.

##### File Structure
- Top-level:
- main.py – entry point configuring FastAPI and mounting routers
- alembic.ini + _meta/_migrations/… – Alembic configuration and revision scripts
- api/
– router.py – central API router
– sample/
- controllers.py – request handlers
- services.py – business-logic layer
- models.py – SQLAlchemy ORM definitions
- schemas.py – Pydantic request/response schemas
- Requirements.txt drives installed frameworks; shortcuts.sh simplifies common commands.
- No separate “frontend” directory—this is backend-only.

##### README
- Describes environment setup (Conda, pip install).
- Walks through Postgres creation, .env variables, and running Alembic migrations.
- Starts the server with “uvicorn main:app --reload --port 8001”.

##### Main Components
a. External Client(s) – e.g. Browser, Mobile App, API Consumer
b. Uvicorn Server + FastAPI App (main.py)
c. API Router (api/router.py)
d. Domain Module (“sample”):
- Controllers
- Services
- Schemas
- Models
e. Database (Postgres)
f. Migration Engine (Alembic)
g. Configuration (.env, alembic.ini)

##### Relationships and Data Flow
- Client → HTTP request → Uvicorn/​FastAPI
- FastAPI → Router → Controller
- Controller → Service → Model (SQLAlchemy ORM)
- Model → SQL operations → Postgres
- Alembic CLI → Migration scripts → Postgres
- Configuration files inject DB credentials into the app and Alembic.

##### Architectural Patterns and Principles
- Layered architecture (Presentation / API layer, Business logic layer, Data access layer).
- Clear separation of concerns: routers map paths to controllers; controllers orchestrate services; services encapsulate business rules; models define the schema.
- Declarative validation via Pydantic schemas.
- Migrations decoupled from runtime code—version-controlled scripts.

– Router (api/router.py)
– Controllers (api/sample/controllers.py)
– Services (api/sample/services.py)
– Schemas & Models (api/sample/schemas.py & models.py)
6. .env / alembic.ini as a config block feeding both the FastAPI app and Alembic.
7. Port 8001 on the server and DB port 5432 on the DB.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["External Clients"]:::client

    %% Uvicorn + FastAPI Layer
    subgraph "Uvicorn + FastAPI" 
        Main["main.py"]:::server
        Router["API Router\n(api/router.py)"]:::api
        Controllers["Controllers\n(api/sample/controllers.py)"]:::api
        Schemas["Schemas\n(api/sample/schemas.py)"]:::data
        Services["Services\n(api/sample/services.py)"]:::service
        Models["Models\n(api/sample/models.py)"]:::data
    end

    %% Database
    DB[(Postgres DB\nbackend_db :5432)]:::db

    %% Migrations and Config
    subgraph "Infrastructure" 
        ConfigFile["Config\n(.env, alembic.ini)"]:::infra
        Migrations["Alembic Migrations\n(_meta/_migrations/)"]:::infra
        Readme["README.md"]:::infra
        Req["requirements.txt"]:::infra
        Shortcuts["shortcuts.sh"]:::infra
    end

    %% Flow of requests
    Client -->|"HTTP Request"| Main
    Main -->|"routes"| Router
    Router -->|"POST /sample"| Controllers
    Controllers -->|"validate"| Schemas
    Schemas -->|"validated data"| Services
    Services -->|"use ORM"| Models
    Models -->|"SELECT/INSERT"| DB

    %% Migrations flow
    Migrations -->|"alembic upgrade head"| DB

    %% Config injections
    ConfigFile -.->|inject DB creds| Main
    ConfigFile -.->|inject DB creds| Migrations

    %% Click events
    click Main "https://github.com/ashbhat/boilerplate_fastapi/blob/main/main.py"
    click Router "https://github.com/ashbhat/boilerplate_fastapi/blob/main/api/router.py"
    click Controllers "https://github.com/ashbhat/boilerplate_fastapi/blob/main/api/sample/controllers.py"
    click Services "https://github.com/ashbhat/boilerplate_fastapi/blob/main/api/sample/services.py"
    click Models "https://github.com/ashbhat/boilerplate_fastapi/blob/main/api/sample/models.py"
    click Schemas "https://github.com/ashbhat/boilerplate_fastapi/blob/main/api/sample/schemas.py"
    click Migrations "https://github.com/ashbhat/boilerplate_fastapi/tree/main/_meta/_migrations/"
    click ConfigFile "https://github.com/ashbhat/boilerplate_fastapi/blob/main/alembic.ini"
    click Readme "https://github.com/ashbhat/boilerplate_fastapi/blob/main/readme.md"
    click Req "https://github.com/ashbhat/boilerplate_fastapi/blob/main/requirements.txt"
    click Shortcuts "https://github.com/ashbhat/boilerplate_fastapi/blob/main/shortcuts.sh"

    %% Styles
    classDef client fill:#AED6F1,stroke:#2E86C1;
    classDef server fill:#D6EAF8,stroke:#2980B9;
    classDef api fill:#D1F2EB,stroke:#1ABC9C;
    classDef service fill:#D5F5E3,stroke:#27AE60;
    classDef data fill:#FCF3CF,stroke:#F1C40F;
    classDef db fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef infra fill:#E8E8E8,stroke:#7F8C8D;
```
