# deight93/fastapi-boilerplate architecture

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

- Interactive diagram: https://gitdiagram.com/deight93/fastapi-boilerplate
- Repository: https://github.com/deight93/fastapi-boilerplate

## Overview

##### Project Type & Purpose
- This is a monolithic backend web API written in Python using FastAPI.
- Primary features: administrator panel, user registration/login, JWT-based auth, token refresh, basic static content.
- It runs in containers (Docker) and uses PostgreSQL for persistence, Redis for caching/sessions, and Alembic for schema migrations.

##### Key File-Tree Insights
- Top-level:
- Dockerfile, docker-compose.yml (+ override/prod) → containerized deployment.
- alembic.ini & migrations/ → database migration setup.
- app/ → main code, subdivided into core (config, middleware, logging), routers (HTTP endpoints), services (business logic), models (ORM), schemas (Pydantic models), admin UI, static assets.
- tests/ → pytest suite.
- Core principles: layered architecture (router → service → model/DB), dependency injection, middleware for cross-cutting concerns, environment-driven configuration.

##### Extracted Technologies & Frameworks
- Runtime: Uvicorn (via “uv”), FastAPI
- Data layer: SQLAlchemy (in app/models + core/database), Alembic for migrations
- Caching/session: Redis
- Auth: JWT (app/core/security + app/services/auth)
- Admin UI: custom pages in app/admin served by FastAPI
- Dev tooling: uv, ruff (lint), pre-commit, pytest, GitHub Actions CI

##### Main Components & Their Roles
A. HTTP Client (e.g., Browser or API client)
B. Load Balancer / Reverse Proxy (optional – e.g., nginx)
C. Uvicorn Server running the FastAPI application
1. Routers (app/routers) – maps HTTP paths to handlers
2. Middleware & Dependency Injection (app/core/middleware + core/dependency)
3. Services (app/services) – business logic (auth, user management)
4. Models & DB Layer (app/models + core/database) – ORM + SQLAlchemy sessions
5. Schemas (app/schemas) – request/response validation (Pydantic)
6. Admin UI & Static Content (app/admin + app/core/static)
D. Datastore: PostgreSQL (Docker service “postgresql-db”)
E. Cache/Session Store: Redis (Docker service “redis-db”)
F. Migration Tool: Alembic (invoked during startup/deployment)
G. CI/CD Pipeline: GitHub Actions (runs uv sync, ruff, pytest)

##### Component Interactions
- HTTP Client → (LB) → Uvicorn/FastAPI
- FastAPI → Routers → Services → Models → PostgreSQL
- Auth Services → Redis (storing refresh tokens or session data)
- FastAPI → Admin UI controllers → static assets served directly or via CDN
- Deployment: Docker Compose spins up API, Postgres, Redis in a shared network
- CI/CD: On push, GitHub Actions container runs tests against a transient Docker Compose environment

##### Architectural Patterns & Design Principles
- Layered Architecture: separation of concerns between HTTP layer (routers), business logic (services), data layer (models).
- Dependency Injection: central in FastAPI via “Depends” for database sessions, settings, security.
- Configuration via environment variables (.env) and app/core/setting.py.
- Middleware for logging, security headers, CORS, etc.
- Database migrations managed by Alembic → versioned SQL scripts.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    HTTPClient["HTTP Client"]:::presentation
    LB["Load Balancer"]:::infra
    HTTPClient -->|HTTP/HTTPS| LB

    %% Docker Compose Boundary
    subgraph "Docker Compose" 
        direction TB

        %% API Container
        subgraph "API Container"
            direction TB
            Main["app/main.py\n(Uvicorn/FastAPI)"]:::application

            subgraph "Core Module"
                direction TB
                Settings["Settings Loader\n(.env → setting.py)"]:::application
                Logger["Logger\n(core/logger.py)"]:::application
                Middleware["Middleware\n(core/middleware.py)"]:::application
                Dependency["Dependency Injection\n(core/dependency.py)"]:::application
                Security["Security\n(core/security.py)"]:::application
                DatabaseCore["DB Connection\n(core/database.py)"]:::application
            end

            subgraph "Routers"
                direction TB
                AuthRouter["auth.py"]:::application
                UserRouter["user.py"]:::application
            end

            subgraph "Services"
                direction TB
                AuthService["auth.py"]:::application
                UserService["user.py"]:::application
            end

            subgraph "Models"
                direction TB
                BaseModel["base.py"]:::data
                UserModel["user.py"]:::data
                AdminModel["admin.py"]:::data
            end

            subgraph "Schemas"
                direction TB
                ReqAuth["request/auth.py"]:::application
                ReqUser["request/user.py"]:::application
                ResAuth["response/auth.py"]:::application
                ResUser["response/user.py"]:::application
                ResBase["response/base.py"]:::application
            end

            subgraph "Admin UI"
                direction TB
                AdminAuthCtrl["auth.py"]:::presentation
                AdminViews["views.py"]:::presentation
            end

            subgraph "Static Content"
                direction TB
                IndexHTML["index.html"]:::presentation
                MainCSS["main.css"]:::presentation
            end

            %% Alembic Migrations
            AlembicInit["alembic.ini"]:::infra
            MigrationsDir["migrations/"]:::infra
        end

        %% Data Stores
        subgraph "PostgreSQL Container"
            direction TB
            Postgres["PostgreSQL\n(Container)"]:::data
        end

        subgraph "Redis Container"
            direction TB
            Redis["Redis\n(Container)"]:::data
        end
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        GitHubActions["GitHub Actions\n(ci.yaml)"]:::infra
        PreCommit["Pre-commit & Lint\n(.pre-commit-config.yaml)"]:::infra
    end

    %% Connections
    LB -->|forwards| Main
    Main -->|loads| Settings
    Main -->|initializes| Logger
    Main -->|registers| Middleware
    Main -->|registers| Dependency
    Main -->|uses| Security
    Main -->|opens session| DatabaseCore
    Main -->|runs migrations| AlembicInit
    AlembicInit -->|scripts| MigrationsDir

    Main -->|includes routers| AuthRouter
    Main -->|includes routers| UserRouter

    AuthRouter -->|calls| AuthService
    UserRouter -->|calls| UserService

    AuthService -->|queries/stores| UserModel
    UserService -->|queries| UserModel

    UserModel -->|persists| Postgres

    AuthService -->|caches/tokens| Redis
    UserService -->|caches| Redis

    Main -->|serves| AdminAuthCtrl
    Main -->|serves| AdminViews
    AdminViews -->|loads| IndexHTML
    AdminViews -->|loads| MainCSS

    GitHubActions -->|runs| PreCommit
    GitHubActions -->|runs tests| Main
    GitHubActions -->|spins up| Postgres
    GitHubActions -->|spins up| Redis

    %% Click Events
    click Main "https://github.com/deight93/fastapi-boilerplate/blob/main/app/main.py"
    click AuthRouter "https://github.com/deight93/fastapi-boilerplate/blob/main/app/routers/auth.py"
    click UserRouter "https://github.com/deight93/fastapi-boilerplate/blob/main/app/routers/user.py"
    click Middleware "https://github.com/deight93/fastapi-boilerplate/blob/main/app/core/middleware.py"
    click Dependency "https://github.com/deight93/fastapi-boilerplate/blob/main/app/core/dependency.py"
    click Settings "https://github.com/deight93/fastapi-boilerplate/blob/main/app/core/setting.py"
    click Logger "https://github.com/deight93/fastapi-boilerplate/blob/main/app/core/logger.py"
    click Security "https://github.com/deight93/fastapi-boilerplate/blob/main/app/core/security.py"
    click DatabaseCore "https://github.com/deight93/fastapi-boilerplate/blob/main/app/core/database.py"
    click BaseModel "https://github.com/deight93/fastapi-boilerplate/blob/main/app/models/base.py"
    click UserModel "https://github.com/deight93/fastapi-boilerplate/blob/main/app/models/user.py"
    click AdminModel "https://github.com/deight93/fastapi-boilerplate/blob/main/app/models/admin.py"
    click ReqAuth "https://github.com/deight93/fastapi-boilerplate/blob/main/app/schemas/request/auth.py"
    click ReqUser "https://github.com/deight93/fastapi-boilerplate/blob/main/app/schemas/request/user.py"
    click ResAuth "https://github.com/deight93/fastapi-boilerplate/blob/main/app/schemas/response/auth.py"
    click ResUser "https://github.com/deight93/fastapi-boilerplate/blob/main/app/schemas/response/user.py"
    click ResBase "https://github.com/deight93/fastapi-boilerplate/blob/main/app/schemas/response/base.py"
    click AuthService "https://github.com/deight93/fastapi-boilerplate/blob/main/app/services/auth.py"
    click UserService "https://github.com/deight93/fastapi-boilerplate/blob/main/app/services/user.py"
    click AdminAuthCtrl "https://github.com/deight93/fastapi-boilerplate/blob/main/app/admin/auth.py"
    click AdminViews "https://github.com/deight93/fastapi-boilerplate/blob/main/app/admin/views.py"
    click IndexHTML "https://github.com/deight93/fastapi-boilerplate/blob/main/app/core/static/index.html"
    click MainCSS "https://github.com/deight93/fastapi-boilerplate/blob/main/app/core/static/main.css"
    click AlembicInit "https://github.com/deight93/fastapi-boilerplate/blob/main/alembic.ini"
    click MigrationsDir "https://github.com/deight93/fastapi-boilerplate/tree/main/migrations/"
    click GitHubActions "https://github.com/deight93/fastapi-boilerplate/blob/main/.github/workflows/ci.yaml"
    click PreCommit "https://github.com/deight93/fastapi-boilerplate/blob/main/.pre-commit-config.yaml"

    %% Styles
    classDef presentation fill:#D0E8FF,stroke:#0366D6;
    classDef application fill:#D0FFD8,stroke:#028A0F;
    classDef data fill:#FFE7C1,stroke:#D97706;
    classDef infra fill:#E2E2E2,stroke:#6B7280;
```
