# arctikant/fastapi-modular-monolith-starter-kit architecture

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

- Interactive diagram: https://gitdiagram.com/arctikant/fastapi-modular-monolith-starter-kit
- Repository: https://github.com/arctikant/fastapi-modular-monolith-starter-kit

## Overview

##### Project type and purpose
- This is a modular-monolith REST API starter kit built on FastAPI.
- It follows a layered architecture (presentation → service → repository) and a modular approach (each feature/module under its own app/<module>).

##### Main components
a. Clients & Entry Points
- External HTTP clients (browsers, mobile apps, services)
- `docker-compose` environment (app container)
b. API Layer (Presentation)
- FastAPI Application (`app/main.py`)
- Core router (`app/core/routers.py`)
- Module routers (e.g. `app/auth/routes/v1/...`)
- Rate Limiter (fastapi-limiter + Redis)
c. Business Logic Layer
- Services in each module (`app/auth/services`, `app/core/services/...`)
- Policies & Gateways (sync cross-module calls, e.g. `AuthGateway`)
- Event dispatch & listeners (`fastapi-events`)
d. Data Access Layer
- Repositories (`app/auth/repositories`, `app/core/db/base_repository.py`)
- SQLAlchemy AsyncSession (`app/core/db/session.py`)
- Migrations (Alembic: `alembic.ini`, `migrations/`)
e. Shared Core Services
- CacheService (aiocache + Redis)
- QueueService (Taskiq + Redis broker)
- MailService (aiosmtplib + MailHog)
- LogService (structlog)
- EventService (fastapi-events)
f. Persistence & External Systems
- PostgreSQL (app container → docker/db/init_scripts)
- Redis (cache, rate limiter, queue)
- SMTP server (MailHog)
g. Infrastructure & Tooling
- Docker / docker-compose
- .env / config system
- CI/testing tools (pytest, factories, coverage)

##### Relationships and interactions
- HTTP Request → FastAPI App → Core Router → Module Router
- Router → Service (via FastAPI DI)
- Service → Repository + AsyncSession → PostgreSQL
- Service ↔ Core Services:
- CacheService (get/set/delete) → Redis
- QueueService.push(...) → Redis broker → Worker
- MailService.send/queue → aiosmtplib → MailHog or Queue
- EventService.dispatch(...) → Event Bus → Listeners
- Gateway dependencies provide sync cross-module calls (e.g. other modules inject `AuthGateway`).
- Rate Limiter applied at router level (ConfigurableRateLimiter → Redis).
- All database models feed into Alembic for migrations.

##### Architectural patterns and design principles
- Layered Architecture: Presentation → Service → Repository → Database
- Modular Monolith: features are self-contained modules under `app/<module>`
- Dependency Injection: FastAPI’s DI system resolves services, session, gateways
- Asynchronous I/O: all external comms (DB, Redis, SMTP) use async libraries
- Separation of Concerns: each core cross-cutting concern (cache, queue, mail, events, logging) lives in its own provider under `app/core/services`
- Gateways & Events: allow easy transition to microservices in the future

##### Emphasize
- Detail each major class or folder as a component.
- Essential interactions (DB, cache, queue, mail, events, rate-limiter).
- Keep the modular boundaries explicit: core vs module vs external infra.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients & Entry Points
    subgraph "Clients & Entry Points" 
        direction TB
        Clients(["External HTTP Clients"]):::external
        DockerCompose(["docker-compose"]):::infra
        Clients -->|HTTP Requests| FastAPIApp
        DockerCompose -->|runs| FastAPIApp
        DockerCompose -->|runs| PostgresDB
        DockerCompose -->|runs| RedisCache
        DockerCompose -->|runs| MailHog
    end

    %% API Layer
    subgraph "API Layer" 
        direction TB
        FastAPIApp["FastAPI App<br/>(app/main.py)"]:::api
        CoreRouter["Core Router<br/>(core/routers.py)"]:::api
        ExceptionHandlers["Exception Handlers<br/>(exception_handlers.py)"]:::api
        Middlewares["Middlewares<br/>(middlewares.py)"]:::api
        RateLimiter["ControlledRateLimiter<br/>(controlled_rate_limiter.py)"]:::api
        FastAPIApp --> CoreRouter
        FastAPIApp --> ExceptionHandlers
        FastAPIApp --> Middlewares
        CoreRouter --> RateLimiter
        subgraph "Auth Module Routers"
            direction TB
            AuthRouter["Auth Routes v1<br/>(auth/routes/v1/auth.py)"]:::api
            ProfileRouter["Profile Routes v1<br/>(auth/routes/v1/profile.py)"]:::api
            UsersRouter["Users Routes v1<br/>(auth/routes/v1/users.py)"]:::api
        end
        RateLimiter --> AuthRouter
        CoreRouter --> ProfileRouter
        CoreRouter --> UsersRouter
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer" 
        direction TB
        AuthService["AuthService<br/>(auth/services/auth.py)"]:::service
        UserService["UserService<br/>(auth/services/user.py)"]:::service
        AuthGateway["AuthGateway<br/>(auth/gateway.py)"]:::service
        EventDefs["Auth Events<br/>(auth/events.py)"]:::service
        CoreListeners["Core Listeners<br/>(core/listeners.py)"]:::service
        AuthRouter -->|Depends on| AuthService
        AuthService -->|Uses| UserService
        AuthService -->|Depends on| AuthGateway
        AuthService -->|Dispatches| EventDefs
        EventDefs -->|Handled by| CoreListeners
    end

    %% Data Access Layer & DB
    subgraph "Data Access & DB" 
        direction TB
        UserRepo["UserRepository<br/>(auth/repositories/user.py)"]:::db
        TokenRepo["RefreshTokenRepository<br/>(auth/repositories/refresh_token.py)"]:::db
        BaseRepo["BaseRepository<br/>(core/db/base_repository.py)"]:::db
        AsyncSession["AsyncSession<br/>(core/db/session.py)"]:::db
        BaseModel["BaseModel<br/>(core/db/base_model.py)"]:::db
        DBExceptions["DB Exceptions<br/>(core/db/exceptions.py)"]:::db
        AuthService -->|await repo methods| UserRepo
        AuthService -->|await repo methods| TokenRepo
        UserRepo --> BaseRepo
        TokenRepo --> BaseRepo
        BaseRepo --> AsyncSession
        BaseModel -->|defines| BaseRepo
    end

    %% Core Services
    subgraph "Core Services" 
        direction TB
        CacheService["CacheService<br/>(core/services/cache/service.py)"]:::core
        QueueService["QueueService<br/>(core/services/queue/service.py)"]:::core
        MailService["MailService<br/>(core/services/mail/service.py)"]:::core
        EventService["EventService<br/>(core/services/events/service.py)"]:::core
        LogService["LogService<br/>(core/services/log/service.py)"]:::core
        AuthService -->|Uses| CacheService
        AuthService -->|Uses| QueueService
        AuthService -->|Uses| MailService
        AuthService -->|Uses| EventService
        AuthService -->|Uses| LogService
    end

    %% External Systems & Infra
    subgraph "Persistence & External Systems" 
        direction TB
        PostgresDB[(PostgreSQL)]:::infra
        RedisCache[(Redis)]:::infra
        MailHogCloud((MailHog SMTP)):::infra
        Alembic["Alembic<br/>(alembic.ini + migrations/)"]:::infra
        AsyncSession -->|connects to| PostgresDB
        CacheService -->|get/set| RedisCache
        RateLimiter -->|rate limit| RedisCache
        QueueService -->|broker| RedisCache
        MailService -->|SMTP| MailHogCloud
        Alembic -->|migrations| PostgresDB
    end

    %% Infrastructure & Tooling
    subgraph "Infrastructure & Tooling" 
        direction TB
        EnvFiles[".env / config"]:::infra
        Dockerfile["Dockerfile"]:::infra
        PreStart["prestart.sh<br/>(backend_pre_start.py)"]:::infra
        Tests["pytest & factories<br/>(tests/)"]:::infra
        FastAPIApp -->|configured by| EnvFiles
        DockerCompose -->|builds| Dockerfile
        FastAPIApp -->|runs prestart| PreStart
        Tests -->|test modules| AuthService
    end

    %% Legend
    subgraph "Legend"
        direction TB
        E1["API Layer"]:::api
        E2["Business Logic"]:::service
        E3["Core Services"]:::core
        E4["Data & Infra"]:::infra
    end

    %% Click Events
    click DockerCompose "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/docker-compose.yaml"
    click FastAPIApp "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/main.py"
    click CoreRouter "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/core/routers.py"
    click ExceptionHandlers "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/core/exception_handlers.py"
    click Middlewares "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/core/middlewares.py"
    click RateLimiter "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/core/api/controlled_rate_limiter.py"
    click AuthRouter "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/auth/routes/v1/auth.py"
    click ProfileRouter "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/auth/routes/v1/profile.py"
    click UsersRouter "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/auth/routes/v1/users.py"
    click AuthService "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/auth/services/auth.py"
    click UserService "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/auth/services/user.py"
    click AuthGateway "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/auth/gateway.py"
    click EventDefs "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/auth/events.py"
    click CoreListeners "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/core/listeners.py"
    click UserRepo "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/auth/repositories/user.py"
    click TokenRepo "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/auth/repositories/refresh_token.py"
    click BaseRepo "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/core/db/base_repository.py"
    click AsyncSession "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/core/db/session.py"
    click BaseModel "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/core/db/base_model.py"
    click DBExceptions "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/core/db/exceptions.py"
    click CacheService "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/core/services/cache/service.py"
    click QueueService "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/core/services/queue/service.py"
    click MailService "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/core/services/mail/service.py"
    click EventService "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/core/services/events/service.py"
    click LogService "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/core/services/log/service.py"
    click Alembic "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/alembic.ini"
    click EnvFiles "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/.sample.env"
    click Dockerfile "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/tree/main/Dockerfile"
    click PreStart "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/app/backend_pre_start.py"
    click Tests "https://github.com/arctikant/fastapi-modular-monolith-starter-kit/blob/main/tests/conftest.py"

    %% Styles
    classDef api fill:#D0E8FF,stroke:#005B96,color:#000
    classDef service fill:#DFF2BF,stroke:#4F8A10,color:#000
    classDef db fill:#FBE8A6,stroke:#C27C00,color:#000
    classDef core fill:#FFE4B5,stroke:#CD8500,color:#000
    classDef infra fill:#E0E0E0,stroke:#707070,color:#000
    classDef external fill:#CCCCFF,stroke:#6666AA,color:#000
```
