# igorbenav/fastapi-boilerplate architecture

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

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

## Overview

##### Project type and purpose
- This is a monolithic, asynchronous REST API boilerplate built with FastAPI, Pydantic V2, SQLAlchemy 2.0, PostgreSQL and Redis.
- It provides user authentication (JWT + cookie‐refresh), Redis caching, rate limiting, ARQ background jobs, Alembic migrations, Docker Compose orchestration, and optional NGINX reverse proxy.

##### File structure
- Top‐level: Dockerfile, docker‐compose.yml, default.conf (NGINX), pyproject.toml, .env template
- src/app
- api/v1: versioned endpoints (login, users, posts, rate_limits, tasks, tiers)
- core: configuration, dependency setup, security, logger, DB (SQLAlchemy + Alembic), exceptions, cache/rate‑limit/queue utils, ARQ worker settings & functions
- crud: generic FastCRUD classes for each model
- models: SQLAlchemy ORM models (User, Post, Tier, RateLimit, TokenBlacklist)
- schemas: Pydantic models for validation/serialization
- middleware: e.g. client_cache_middleware
- main.py: application entrypoint
- src/migrations: Alembic scripts
- src/scripts: helper scripts to create first superuser & tier
- tests: pytest fixtures, helpers, unit tests

##### README insights
- Technology stack badges (Python, FastAPI, Pydantic, PostgreSQL, Redis, Docker, NGINX)
- Feature list: async, JWT auth, cookie refresh, client & server caching, ARQ queue, fastcrud, pagination, rate limiter, docs gating, extensibility
- Deployment instructions: Docker Compose up → services web, db, worker, redis, optional nginx & pgadmin
- Production: Gunicorn+Uvicorn, NGINX reverse proxy, multiple servers support

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Client["Clients"]:::external

    %% Reverse Proxy
    NGINX["NGINX Reverse Proxy :80"]:::infra

    %% Web Service
    subgraph "Web Service (FastAPI Uvicorn :8000)"
        Main["main.py"]:::service
        API["API Endpoints (v1)"]:::service
        Deps["API Dependencies"]:::service
        Config["Core Config"]:::service
        Setup["Core Setup"]:::service
        Sec["Security"]:::service
        Logger["Logger"]:::service
        DBConn["DB Connection"]:::service
        ModelsCore["Core Models"]:::service
        TokenBL["Token Blacklist CRUD"]:::service
        CacheEx["Cache Exceptions"]:::service
        HTTPEx["HTTP Exceptions"]:::service
        CacheUtil["Cache Utility"]:::service
        RateLimitUtil["Rate Limiting Utility"]:::service
        QueueUtil["Queue Utility"]:::service
        Middleware["Middleware"]:::service
    end

    %% Worker Service
    subgraph "ARQ Worker Service"
        WorkerSettings["Worker Settings"]:::service
        WorkerFuncs["Worker Functions"]:::service
    end

    %% Data Stores
    subgraph "Data Stores"
        Postgres["PostgreSQL"]:::data
        Redis["Redis"]:::data
    end

    %% Tooling & Others
    subgraph "Tooling & Infrastructure"
        PGAdmin["PGAdmin"]:::tooling
        Alembic["Alembic Migrations"]:::tooling
        Migrations["Migrations Scripts"]:::tooling
        Scripts["Helper Scripts"]:::tooling
        Compose["Docker Compose"]:::infra
        DockerfileF["Dockerfile"]:::infra
        Tests["Test Suite"]:::tooling
    end

    %% Connections
    Client -->|"HTTP/HTTPS"| NGINX
    NGINX -->|"HTTP/HTTPS"| Main
    Main --> API
    API --> Deps
    Deps --> Config
    Deps --> Setup
    Deps --> Sec
    Deps --> Logger
    Deps --> DBConn
    Deps --> ModelsCore
    Deps --> TokenBL
    Deps --> CacheEx
    Deps --> HTTPEx
    Deps --> CacheUtil
    Deps --> RateLimitUtil
    Deps --> QueueUtil
    Deps --> Middleware

    DBConn -->|"SQL queries"| Postgres
    ModelsCore --> Postgres
    TokenBL --> Postgres

    Main -->|"Redis GET/SET"| Redis
    CacheUtil --> Redis
    RateLimitUtil --> Redis
    QueueUtil --> Redis

    Main -->|"ARQ enqueue"| Redis
    Redis -->|"ARQ dequeue"| WorkerSettings
    Redis -->|"ARQ dequeue"| WorkerFuncs
    WorkerSettings --> Redis
    WorkerFuncs --> Redis
    WorkerSettings -->|"SQL queries"| Postgres
    WorkerFuncs -->|"SQL queries"| Postgres

    Alembic -->|"migrations"| Postgres
    Migrations --> Postgres

    Scripts --> Postgres
    Compose --> NGINX
    Compose --> Main
    Compose --> Postgres
    Compose --> Redis
    Compose --> WorkerSettings
    Compose --> PGAdmin
    Compose --> Tests

    Tests --> Main

    %% Click Events
    click Main "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/main.py"
    click API "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/api/v1/*.py"
    click Deps "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/api/dependencies.py"
    click Config "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/core/config.py"
    click Setup "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/core/setup.py"
    click Sec "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/core/security.py"
    click Logger "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/core/logger.py"
    click DBConn "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/core/db/database.py"
    click ModelsCore "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/core/db/models.py"
    click TokenBL "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/core/db/crud_token_blacklist.py"
    click CacheEx "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/core/exceptions/cache_exceptions.py"
    click HTTPEx "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/core/exceptions/http_exceptions.py"
    click CacheUtil "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/core/utils/cache.py"
    click RateLimitUtil "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/core/utils/rate_limit.py"
    click QueueUtil "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/core/utils/queue.py"
    click WorkerSettings "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/core/worker/settings.py"
    click WorkerFuncs "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/app/core/worker/functions.py"
    click Alembic "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/alembic.ini"
    click Migrations "https://github.com/igorbenav/fastapi-boilerplate/tree/main/src/migrations/"
    click Scripts "https://github.com/igorbenav/fastapi-boilerplate/blob/main/src/scripts/create_first_superuser.py"
    click Compose "https://github.com/igorbenav/fastapi-boilerplate/blob/main/docker-compose.yml"
    click DockerfileF "https://github.com/igorbenav/fastapi-boilerplate/tree/main/Dockerfile"
    click NGINX "https://github.com/igorbenav/fastapi-boilerplate/blob/main/default.conf"
    click Tests "https://github.com/igorbenav/fastapi-boilerplate/blob/main/tests/conftest.py"

    %% Styles
    classDef service fill:#cce5ff,stroke:#004085,color:#004085;
    classDef data fill:#d4edda,stroke:#155724,color:#155724;
    classDef infra fill:#fff3cd,stroke:#856404,color:#856404;
    classDef tooling fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external fill:#f8f9fa,stroke:#6c757d,color:#6c757d;
```
