# hdn24/fastapi-boilerplate architecture

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

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

## Overview

##### Main Components
- Backend API: The core of the project is in the “app” directory, with submodules for API endpoints (routers), business logic (cruds), data models (models), and schemas (for data validation with Pydantic). This forms the FastAPI service handling HTTP requests.
- Deployment/Containerization: Docker is used for both local and production setups (see docker-compose.yml and docker/Dockerfile). Clearly denote the Docker containers and the orchestration provided by Docker Compose.
- CI/CD & Testing: GitHub Actions are set up for continuous integration (see .github/workflows folder) and there are integration tests under “app/tests”. Mark these as supporting components for continuous quality assurance.
- Reverse Proxy: There is an “nginx” directory with configuration files. This likely serves as a reverse proxy or load balancer on the deployment side. Include a component for Nginx that sits at the front of the architecture.
- Utilities and Configuration: The app has central configuration files (configs.py, database.py, dependencies.py) that tie together settings and dependency management. Although not separate services, they are important for overall architecture clarity.

##### Relationships and Interactions
- A clear data flow from the client requests (could be browsers or API consumers) to the FastAPI service.
- Nginx as an external gateway or reverse proxy that routes incoming requests to the FastAPI backend.
- CI/CD pipeline (GitHub Actions) as an external process triggering builds and tests and pushing updates.
- How Docker Compose orchestrates these containers (backend, database, possibly nginx) and mention that Docker container builds are specified in Docker-related files.

##### Architectural Patterns and Design Principles
- Containerized Deployment: Emphasize the use of Docker, which means each main component (backend service, database, proxy) can be visualized as distinct containers communicating over defined networks.

##### Relevant Technologies and Frameworks
- FastAPI for building the web API
- SQLAlchemy as the ORM for PostgreSQL
- Pydantic for schema validation and settings
- Docker and Docker Compose for containerization and orchestration
- Nginx as the reverse proxy
- GitHub Actions for CI/CD workflows
- Poetry as the dependency management tool for Python

- FastAPI container: split internally to show its organization into routers, cruds, models, and schemas.
- Outside of this containerized environment, add an element for CI/CD (GitHub Actions) tied to the source code repository.
- Optionally, include a “Testing” component that highlights the integration tests and how they interact with the FastAPI service.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Client (API Consumer)"]:::external

    %% CI/CD Pipeline
    CICD["CI/CD Pipeline (GitHub Actions)"]:::cicd

    %% Docker Compose Orchestration
    DockerCompose["Docker Compose Orchestration"]:::container

    %% Containerized Environment
    subgraph "Containerized Environment"
        direction TB

        %% Nginx Container
        Nginx["Nginx Reverse Proxy"]:::nginx

        %% FastAPI Container with internal structure
        subgraph "FastAPI Container"
            direction TB
            FASTAPI["FastAPI Service"]:::backend
            Routers["API Endpoints (routers)"]:::module
            Cruds["Business Logic (cruds)"]:::module
            Models["Data Models"]:::module
            Schemas["Schemas (Pydantic)"]:::module
            Configs["Configurations"]:::config
            Dependencies["Central Dependencies"]:::config
            ORMSetup["Database Configuration (ORM)"]:::db
        end

        %% PostgreSQL Container
        PostgreSQL["PostgreSQL Database"]:::database
    end

    %% Dockerfile Node for container configuration
    Dockerfile["Docker Container Configuration"]:::containerConfig

    %% Integration Tests
    Tests["Integration Tests"]:::test

    %% Relationships
    Client -->|"sends requests"| Nginx
    Nginx -->|"forwards to"| FASTAPI
    FASTAPI -->|"calls"| PostgreSQL
    PostgreSQL -- "responds to" --> FASTAPI

    %% Internal FastAPI structure connections
    FASTAPI -->|"uses"| Routers
    FASTAPI -->|"uses"| Cruds
    FASTAPI -->|"uses"| Models
    FASTAPI -->|"validates with"| Schemas
    FASTAPI -->|"configured by"| Configs
    FASTAPI -->|"has dependency"| Dependencies
    FASTAPI -->|"sets ORM"| ORMSetup

    %% Docker Compose orchestrates the containers
    DockerCompose --> Nginx
    DockerCompose --> FASTAPI
    DockerCompose --> PostgreSQL

    %% CI/CD Pipeline triggers deployment
    CICD -->|"triggers build"| DockerCompose

    %% Integration tests interact with FastAPI
    Tests -->|"tests API"| FASTAPI

    %% Docker Compose also references Dockerfile
    DockerCompose -->|"build config"| Dockerfile

    %% Click Events
    click FASTAPI "https://github.com/hdn24/fastapi-boilerplate/blob/develop/app/main.py"
    click Routers "https://github.com/hdn24/fastapi-boilerplate/tree/develop/app/api/routers"
    click Cruds "https://github.com/hdn24/fastapi-boilerplate/tree/develop/app/api/cruds"
    click Models "https://github.com/hdn24/fastapi-boilerplate/tree/develop/app/api/models"
    click Schemas "https://github.com/hdn24/fastapi-boilerplate/tree/develop/app/api/schemas"
    click ORMSetup "https://github.com/hdn24/fastapi-boilerplate/blob/develop/app/database.py"
    click DockerCompose "https://github.com/hdn24/fastapi-boilerplate/blob/develop/docker-compose.yml"
    click Dockerfile "https://github.com/hdn24/fastapi-boilerplate/tree/develop/docker/Dockerfile"
    click CICD "https://github.com/hdn24/fastapi-boilerplate/blob/develop/.github/workflows/ci.yml"
    click Tests "https://github.com/hdn24/fastapi-boilerplate/tree/develop/app/tests/integration"
    click Nginx "https://github.com/hdn24/fastapi-boilerplate/blob/develop/nginx/conf/app.conf"
    click Configs "https://github.com/hdn24/fastapi-boilerplate/blob/develop/app/configs.py"
    click Dependencies "https://github.com/hdn24/fastapi-boilerplate/blob/develop/app/dependencies.py"

    %% Styles
    classDef external fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px
    classDef backend fill:#AED6F1,stroke:#3498DB,stroke-width:2px
    classDef module fill:#D7BDE2,stroke:#8E44AD,stroke-width:2px
    classDef database fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px
    classDef container fill:#D5F5E3,stroke:#27AE60,stroke-width:2px
    classDef cicd fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px
    classDef nginx fill:#D6EAF8,stroke:#5DADE2,stroke-width:2px
    classDef test fill:#FADBD8,stroke:#E67E22,stroke-width:2px
    classDef config fill:#EBDEF0,stroke:#AF7AC5,stroke-width:2px
    classDef containerConfig fill:#E8DAEF,stroke:#9B59B6,stroke-width:2px
```
