# jeca514/full-stack-fastapi-template architecture

> Architecture diagram of the GitHub repository jeca514/full-stack-fastapi-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/jeca514/full-stack-fastapi-template
- Repository: https://github.com/jeca514/full-stack-fastapi-template

## Overview

##### Main components
- Backend API: This is built with FastAPI, using SQLModel (with PostgreSQL) for ORM, and includes modules for dependency injection (see backend/app/api), core configuration (backend/app/core), email templates (backend/app/email-templates), database migrations (alembic), and tests.
- Frontend Application: Built with React, it includes components (found in frontend/src/components), hooks, and auto-generated API client code. It leverages modern tooling such as Vite and TypeScript.
- Database: PostgreSQL is the primary datastore. Configuration and connection management occur within the backend’s core files.
- Containerization & Deployment: Docker Compose files (docker-compose.yml, docker-compose.override.yml, docker-compose.traefik.yml) manage both the backend and frontend containers, and Traefik is used for routing and HTTPS provisioning.
- CI/CD Pipelines: GitHub Actions workflows (under .github/workflows) automate running tests, linting, deployments, and generating clients.
- Auxiliary components: Email service integration for password recovery, JWT authentication mechanism, and miscellaneous scripts for formatting, testing, and pre-deployment tasks.

##### Relationships and interactions
- The Backend connects to the Database (PostgreSQL) using SQLModel; indicate a connection showing data CRUD operations.
- Docker Compose ties these components together as separate services; include symbols for containers and network connections.
- Traefik acts as a reverse proxy to forward client requests from the frontend or external endpoints to the appropriate service.

##### Architectural patterns and design principles
- Use of dependency injection and modular design in the backend (with routes, core, and CRUD components isolated).
- Containerization and reproducibility using Docker Compose, reflecting a microservices-style orchestration even if all services run in a unified environment.
- Additional layers such as the reverse proxy (Traefik) which abstracts traffic management and SSL/TLS termination.

##### Relevant technologies, frameworks, and libraries
- Backend: FastAPI, SQLModel, Pydantic, Alembic for migrations, JWT authentication, and pytest for testing.
- Frontend: React, TypeScript, Vite, Chakra UI, and Playwright for end-to-end testing.
- Infrastructure: Docker Compose for containerized deployment, Traefik for reverse proxying, and GitHub Actions for CI/CD.
- Other: Copier for project templating and environment configuration management through .env files.

- Clear labels for each major component: “Frontend (React + Vite)”, “Backend API (FastAPI + SQLModel)”, “PostgreSQL Database”, “Traefik Reverse Proxy”, and “CI/CD Pipeline (GitHub Actions)”.
- User requests coming into the Traefik proxy.
- Requests being forwarded to the frontend and backend.
- API calls from the frontend to the backend.
- Backend interactions with the PostgreSQL database.
- Data flowing from the CI/CD system into deployment (triggering Docker Compose builds and container updates).
- Clearly mention the role of Docker Compose which acts as the integrator by defining multiple services such as the frontend, backend, and Traefik service.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User("User"):::user

    %% Infrastructure Layer
    subgraph "Infrastructure"
        DC("Docker Compose"):::infra
        DCO("Docker Compose Override"):::infra
        TRAEFIK("Traefik Reverse Proxy"):::infra
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        FE("Frontend Application (React + Vite)"):::frontend
        FEC("Frontend Components"):::frontend
        FEAPI("API Client"):::frontend
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        AR("API Routes (FastAPI)"):::backend
        MA("Main App (FastAPI)"):::backend
        DEP("Dependency Injection"):::backend
        CCS("Core Config & Security"):::backend
        ET("Email Templates"):::backend
        DM("Database Migrations"):::backend
        BT("Backend Tests"):::backend
    end

    %% Data Layer
    DB("PostgreSQL Database"):::database

    %% CI/CD Layer
    CI("CI/CD Pipeline (GitHub Actions)"):::ci

    %% Flow of Requests and Deployments
    User -->|"HTTPS"| TRAEFIK
    TRAEFIK -->|"Forwards"| FE
    TRAEFIK -->|"Forwards"| AR
    FE -->|"APIcall"| AR
    AR -->|"CRUD"| DB

    CI -->|"Deploy"| DC
    CI -->|"Deploy"| DCO
    CI -->|"Deploy"| TRAEFIK

    DC --> FE
    DCO --> FE
    DC --> AR
    DCO --> AR

    %% Internal Backend Flow
    AR --> MA
    MA --> DEP
    DEP --> CCS
    CCS --> DM
    AR --> ET
    BT --- AR

    %% Frontend Internal Composition
    FE --> FEC
    FE --> FEAPI

    %% Click Events
    click AR "https://github.com/jeca514/full-stack-fastapi-template/tree/master/backend/app/api"
    click MA "https://github.com/jeca514/full-stack-fastapi-template/blob/master/backend/app/main.py"
    click DEP "https://github.com/jeca514/full-stack-fastapi-template/blob/master/backend/app/api/deps.py"
    click CCS "https://github.com/jeca514/full-stack-fastapi-template/tree/master/backend/app/core"
    click ET "https://github.com/jeca514/full-stack-fastapi-template/tree/master/backend/app/email-templates"
    click DM "https://github.com/jeca514/full-stack-fastapi-template/tree/master/backend/app/alembic"
    click BT "https://github.com/jeca514/full-stack-fastapi-template/tree/master/backend/app/tests"
    click FE "https://github.com/jeca514/full-stack-fastapi-template/tree/master/frontend/"
    click FEC "https://github.com/jeca514/full-stack-fastapi-template/tree/master/frontend/src/components"
    click FEAPI "https://github.com/jeca514/full-stack-fastapi-template/tree/master/frontend/src/client"
    click DC "https://github.com/jeca514/full-stack-fastapi-template/blob/master/docker-compose.yml"
    click DCO "https://github.com/jeca514/full-stack-fastapi-template/blob/master/docker-compose.override.yml"
    click TRAEFIK "https://github.com/jeca514/full-stack-fastapi-template/blob/master/docker-compose.traefik.yml"
    click CI "https://github.com/jeca514/full-stack-fastapi-template/tree/master/.github/workflows"

    %% Style Classes
    classDef user fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef frontend fill:#AED6F1,stroke:#21618C,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef database fill:#82E0AA,stroke:#1E8449,stroke-width:2px;
    classDef infra fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef ci fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
```
