# zhanymkanov/fastapi_production_template architecture

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

- Interactive diagram: https://gitdiagram.com/zhanymkanov/fastapi_production_template
- Repository: https://github.com/zhanymkanov/fastapi_production_template

## Overview

##### Main system components
- FastAPI Application – The core API logic is implemented in the "src" directory, with src/main.py as the entry point and additional modules for configuration, constants, database connectivity, utils, etc.
- Database – Postgres is used as the persistent storage, and there are scripts in the “scripts/postgres” directory to handle backups and restores. The configuration and migrations (using Alembic) further emphasize the database’s central role.
- Migration System – The “alembic” directory contains scripts and configuration for handling migrations, which is an essential part of managing the database schema.
- Production Components – Docker (via Dockerfile.prod and docker-compose.prod.yml), Gunicorn (via the gunicorn directory and entrypoints scripts), and logging configurations (logging.ini, logging_production.ini) provide production-readiness.
- Development Utilities – Environment setups, linting (ruff via the configuration files and justfile commands), and poetry configuration.

- Optionally, show the external tooling layer that uses just commands and poetry for local development, highlighting that these scripts automate tasks like running the development server, linting, and managing migrations.

##### Architectural patterns and technologies
- Separation of concerns: configuration management (src/config.py), main server logic (src/main.py), and database components (src/database.py & alembic migrations).
- That production deployments are managed through Docker and docker-compose, which orchestrates the infrastructure (both API container and Postgres server container).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    subgraph "API Layer"
        AP["FastAPI Application (main.py, src)"]:::apiColor
    end

    %% Database Layer
    subgraph "Database Layer"
        DB["Postgres Database"]:::dbColor
        DS["Backup/Restore Scripts"]:::scriptColor
    end

    %% Migration System
    subgraph "Migration System"
        MIG["Alembic Migrations"]:::migColor
    end

    %% Production Deployment
    subgraph "Production Deployment"
        DF["Dockerfile"]:::prodColor
        DC["Docker Compose"]:::prodColor
        G["Gunicorn Server"]:::prodColor
        L["Logging Config"]:::prodColor
    end

    %% Development Tools
    subgraph "Development Tools"
        DEV["Development Tools (Just, Poetry, Ruff)"]:::devColor
    end

    %% Connections
    DS -->|"Backup/Restore"| DB
    AP -->|"SQLAlchemyOps"| DB
    MIG -->|"SchemaMigration"| DB

    DF --> AP
    DC --> AP
    G -->|"ServeAPI"| AP
    L -->|"Logging"| G
    DC -->|"Orchestrates"| DB

    DEV -->|"RunAPI"| AP
    DEV -->|"ManageMigrations"| MIG

    %% Click Events
    click AP "https://github.com/zhanymkanov/fastapi_production_template/blob/main/src/main.py"
    click DB "https://github.com/zhanymkanov/fastapi_production_template/blob/main/src/database.py"
    click DS "https://github.com/zhanymkanov/fastapi_production_template/tree/main/scripts/postgres"
    click MIG "https://github.com/zhanymkanov/fastapi_production_template/tree/main/alembic"
    click DF "https://github.com/zhanymkanov/fastapi_production_template/blob/main/Dockerfile.prod"
    click DC "https://github.com/zhanymkanov/fastapi_production_template/blob/main/docker-compose.prod.yml"
    click G "https://github.com/zhanymkanov/fastapi_production_template/blob/main/entrypoints/gunicorn.sh"
    click G "https://github.com/zhanymkanov/fastapi_production_template/blob/main/gunicorn/gunicorn_conf.py"
    click L "https://github.com/zhanymkanov/fastapi_production_template/blob/main/logging.ini"
    click L "https://github.com/zhanymkanov/fastapi_production_template/blob/main/logging_production.ini"
    click DEV "https://github.com/zhanymkanov/fastapi_production_template/tree/main/justfile"
    click DEV "https://github.com/zhanymkanov/fastapi_production_template/blob/main/pyproject.toml"
    click DEV "https://github.com/zhanymkanov/fastapi_production_template/blob/main/ruff.toml"

    %% Styles
    classDef apiColor fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef dbColor fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef scriptColor fill:#f9844a,stroke:#333,stroke-width:2px;
    classDef migColor fill:#f94144,stroke:#333,stroke-width:2px;
    classDef prodColor fill:#577590,stroke:#333,stroke-width:2px;
    classDef devColor fill:#277da1,stroke:#333,stroke-width:2px;
```
