# beerjoa/fastapi-postgresql-boilerplate architecture

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

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

## Overview

##### Main Components

a) Client Layer:
- External clients (Web/Mobile applications)
- Swagger UI/ReDoc for API documentation

b) API Layer:
- FastAPI Application Server
- API Routes (v1)
- Authentication Middleware
- Dependencies Injection System

c) Service Layer:
- User Service
- Authentication Service

d) Repository Layer:
- Base Repository
- User Repository

e) Database Layer:
- PostgreSQL Database
- Alembic Migrations

##### Component Relationships and Interactions

**Client Layer → API Layer → Service Layer → Repository Layer → Database Layer**

##### Specific Implementation Details

a) API Layer Components:
- Routes (/api/v1/auth, /api/v1/users)
- JWT authentication flow
- Dependency injection container

b) Service Layer Details:
- Service result pattern implementation
- Error handling and business logic

c) Data Flow Components:
- Schema validation (app/schemas)
- Model definitions (app/models)
- Database migrations

##### Technical Elements to Highlight

- FastAPI framework
- SQLAlchemy ORM
- Alembic migrations
- Poetry dependency management
- Docker containerization

**[External Clients/Documentation]**
- ↓
**[FastAPI Application (Main Router)]**
- ↓
**[Authentication & Dependencies]**
- ↓
**[API Routes (v1)]**
- ↓
**[Services Layer]**
- ↓
**[Repositories]**
- ↓
**[PostgreSQL Database]**

##### Important Details

- Configuration management (app/core/settings)
- Error handling flow (app/utils/app_exceptions)
- Custom logging implementation
- Environment-specific settings (dev, prod, test)

##### The data flow through the application

Remember to maintain a balance between detail and clarity, focusing on the architectural patterns while avoiding overwhelming implementation details. Use standardized UML or similar notation for consistency and clarity.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        WEB["Web Client"]
        MOB["Mobile Client"]
        DOC["API Documentation"]:::docs
    end

    subgraph APILayer["API Layer"]
        MAIN["FastAPI Application"]:::main
        click MAIN "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/main.py"
        
        subgraph Routes["API Routes v1"]
            AUTH["/api/v1/auth"]:::api
            USERS["/api/v1/users"]:::api
            click AUTH "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/api/v1/auth.py"
            click USERS "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/api/v1/users.py"
        end

        subgraph Security
            AUTHMW["Authentication Middleware"]:::security
            TOKEN["Token Management"]:::security
            SECCORE["Security Core"]:::security
            click TOKEN "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/core/token.py"
            click SECCORE "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/core/security.py"
            click AUTHMW "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/api/dependencies/auth.py"
        end
    end

    subgraph ServiceLayer["Service Layer"]
        BASESERV["Base Service"]:::service
        USERSERV["User Service"]:::service
        SERVRES["Service Result Handler"]:::service
        click BASESERV "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/services/base.py"
        click USERSERV "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/services/users.py"
        click SERVRES "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/utils/service_result.py"
    end

    subgraph RepositoryLayer["Repository Layer"]
        BASEREP["Base Repository"]:::repository
        USERREP["User Repository"]:::repository
        click BASEREP "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/database/repositories/base.py"
        click USERREP "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/database/repositories/users.py"
    end

    subgraph DataLayer["Data Layer"]
        DB[(PostgreSQL)]:::database
        DBEVENTS["Database Events"]:::database
        MIGRATIONS["Alembic Migrations"]:::database
        click DBEVENTS "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/database/events.py"
        click MIGRATIONS "https://github.com/beerjoa/fastapi-postgresql-boilerplate/tree/main/app/database/migrations/"
    end

    subgraph Config["Configuration"]
        SETTINGS["Base Settings"]:::config
        DEV["Development Config"]:::config
        PROD["Production Config"]:::config
        TEST["Test Config"]:::config
        click SETTINGS "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/core/settings/base.py"
        click DEV "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/core/settings/dev.py"
        click PROD "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/core/settings/prod.py"
        click TEST "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/core/settings/test.py"
    end

    subgraph ErrorHandling["Error Handling"]
        APPERR["Application Exceptions"]:::error
        REQERR["Request Exceptions"]:::error
        click APPERR "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/utils/app_exceptions.py"
        click REQERR "https://github.com/beerjoa/fastapi-postgresql-boilerplate/blob/main/app/utils/request_exceptions.py"
    end

    %% Relationships
    WEB & MOB & DOC --> MAIN
    MAIN --> Routes
    Routes --> Security
    Security --> ServiceLayer
    ServiceLayer --> RepositoryLayer
    RepositoryLayer --> DataLayer
    Config --> MAIN
    ErrorHandling --> MAIN

    %% Styling
    classDef main fill:#1E88E5,color:white
    classDef api fill:#42A5F5,color:white
    classDef security fill:#FF5252,color:white
    classDef service fill:#66BB6A,color:white
    classDef repository fill:#FFA726,color:white
    classDef database fill:#78909C,color:white
    classDef config fill:#7E57C2,color:white
    classDef error fill:#EC407A,color:white
    classDef docs fill:#26A69A,color:white
```
