# buuntu/fastapi-react architecture

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

- Interactive diagram: https://gitdiagram.com/buuntu/fastapi-react
- Repository: https://github.com/buuntu/fastapi-react

## Overview

##### Project Type and Purpose
- This is a full-stack, containerized web application template combining:
- A FastAPI back-end (Python) providing a JWT-secured REST API and background tasks via Celery/Redis.
- A React front-end (TypeScript, MaterialUI + react-admin) consuming that API.
- PostgreSQL for persistence, Alembic for migrations.
- Docker Compose orchestrating containers (frontend, backend, DB, Redis, Celery, Flower, Nginx).

##### Main Components
a. Reverse Proxy (Nginx)
- nginx.conf routes incoming HTTP(S) to either the React dev server/static build or the FastAPI Uvicorn server.
b. Frontend Service
- React application served by a Node.js container (development server via `npm start` or static files in production).
- Contains routes (login, home, protected), utilities (auth, API calls), and an admin dashboard (react-admin).
c. Backend Service
- FastAPI application running under Uvicorn/Gunicorn.
- API layer: routers (auth.py, users.py) organized under `/app/api/api_v1/routers`.
- Core logic: authentication, config, Celery app, security, dependencies.
- Persistence: SQLAlchemy models/schemas, session management, Alembic migrations, initial_data loader.
- Background tasks: `app/tasks.py`, Celery configured to use Redis broker.
d. Database
- PostgreSQL container, accessed by FastAPI (CRUD operations) and by tests via `test_db` fixture.
e. Message Broker & Workers
- Redis as Celery broker.
- Celery worker container consuming tasks.
- Flower container for monitoring tasks at port 5555.
f. CI / CD and Scripts
- GitHub Actions for builds, Dependabot config.
- Local scripts (`build.sh`, `test.sh`, etc.) for building images, running tests, migrations.

##### Component Interactions and Data Flows
- Client → Nginx: All HTTP traffic enters through Nginx.
- Nginx → Frontend: Routes `GET /`, static files or dev server proxy.
- Frontend ↔ Backend: React invokes REST endpoints under `/api/v1/...` using JWT in headers.
- Backend → PostgreSQL: CRUD via SQLAlchemy sessions.
- Backend → Redis: Celery tasks dispatched to broker.
- Redis → Celery Workers: Workers pick up tasks, optionally perform DB operations.
- Celery Workers → Flower: Flower polls broker/worker metrics.

##### Architectural Patterns and Design Principles
- Layered Architecture: Presentation (React), API/Business (FastAPI), Data (PostgreSQL), Background Processing (Celery).
- Containerization & Microservices: Each logical component runs in its own Docker container, networked via Docker Compose.
- Separation of Concerns:
- Frontend (`frontend/`) vs. Admin (`frontend/src/admin/`) vs. Utils.
- Backend modules: routers, core, db, tasks.
- Infrastructure as Code: Dockerfiles, compose file, Nginx config, scripts.
- Testing Strategy: Pytest fixtures isolate test DB and clients; React unit tests under `__tests__`.

##### Technologies and Frameworks
- Frontend: React, react-router, MaterialUI, react-admin, TypeScript, ESLint/Prettier.
- Backend: FastAPI, Uvicorn/Gunicorn, Pydantic, SQLAlchemy, Alembic, PyJWT, Celery, Redis.
- Database: PostgreSQL.
- Orchestration: Docker Compose, Nginx.
- CI/CD: GitHub Actions, Dependabot.

##### Essential Elements Checklist
- Logical grouping of frontend, backend, data, and infrastructure.
- Port numbers and network names.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Entry
    User["User"]:::external
    User -->|"HTTP/HTTPS"| Nginx

    %% Reverse Proxy
    subgraph "Reverse Proxy"
        Nginx["Nginx (80/443)"]:::proxy
    end
    click Nginx "https://github.com/buuntu/fastapi-react/blob/master/{{cookiecutter.project_slug}}/nginx/nginx.conf"

    %% Frontend Layer
    subgraph "Frontend Layer"
        ReactContainer["Frontend (React)"]:::frontend
        DevServer["React Dev Server (3000)"]:::frontend
        StaticServe["Static Build"]:::frontend
        ReactContainer --> DevServer
        ReactContainer --> StaticServe
    end
    click ReactContainer "https://github.com/buuntu/fastapi-react/tree/master/{{cookiecutter.project_slug}}/frontend/Dockerfile"
    click DevServer "https://github.com/buuntu/fastapi-react/blob/master/{{cookiecutter.project_slug}}/frontend/src/index.tsx"
    click StaticServe "https://github.com/buuntu/fastapi-react/blob/master/{{cookiecutter.project_slug}}/frontend/public/index.html"

    %% Backend Layer
    subgraph "Backend Layer"
        BackendContainer["Backend (FastAPI/Uvicorn 8000)"]:::backend
        subgraph "API Layer"
            Routers["Routers\n(auth.py, users.py)"]:::backend
        end
        subgraph "Core & Security"
            CoreConfig["Config & Security"]:::backend
            CeleryApp["Celery App Init"]:::backend
        end
        subgraph "DB & Migrations"
            Models["Models/Schemas/CRUD"]:::database
            Migrations["Alembic Migrations"]:::database
        end
        subgraph "Tasks"
            Tasks["Background Tasks"]:::broker
        end
        BackendContainer --> Routers
        BackendContainer --> CoreConfig
        BackendContainer --> CeleryApp
        BackendContainer --> Models
        BackendContainer --> Migrations
        BackendContainer --> Tasks
    end
    click BackendContainer "https://github.com/buuntu/fastapi-react/tree/master/{{cookiecutter.project_slug}}/backend/Dockerfile"
    click Routers "https://github.com/buuntu/fastapi-react/blob/master/{{cookiecutter.project_slug}}/backend/app/api/api_v1/routers/auth.py"
    click CoreConfig "https://github.com/buuntu/fastapi-react/blob/master/{{cookiecutter.project_slug}}/backend/app/core/config.py"
    click CeleryApp "https://github.com/buuntu/fastapi-react/blob/master/{{cookiecutter.project_slug}}/backend/app/core/celery_app.py"
    click Models "https://github.com/buuntu/fastapi-react/blob/master/{{cookiecutter.project_slug}}/backend/app/db/models.py"
    click Migrations "https://github.com/buuntu/fastapi-react/blob/master/{{cookiecutter.project_slug}}/backend/app/alembic/env.py"
    click Tasks "https://github.com/buuntu/fastapi-react/blob/master/{{cookiecutter.project_slug}}/backend/app/tasks.py"

    %% Data & Broker
    subgraph "Data & Messaging"
        Postgres["PostgreSQL (5432)"]:::database
        Redis["Redis (6379)"]:::broker
        Worker["Celery Worker"]:::broker
        Flower["Flower (5555)"]:::broker
    end
    click Postgres "https://github.com/buuntu/fastapi-react/blob/master/{{cookiecutter.project_slug}}/backend/app/alembic/versions/91979b40eb38_create_users_table.py"

    %% CI/CD & Scripts
    subgraph "CI/CD & Scripts"
        Actions["GitHub Actions"]:::infra
        Dependabot["Dependabot Config"]:::infra
        Scripts["Local Scripts"]:::infra
    end
    click Actions "https://github.com/buuntu/fastapi-react/blob/master/.github/workflows/config.yml"
    click Dependabot "https://github.com/buuntu/fastapi-react/blob/master/.dependabot/config.yml"
    click Scripts "https://github.com/buuntu/fastapi-react/blob/master/scripts/build.sh"

    %% Docker Compose Network
    DockerCompose["Docker Compose"]:::infra
    click DockerCompose "https://github.com/buuntu/fastapi-react/blob/master/{{cookiecutter.project_slug}}/docker-compose.yml"

    %% Connections
    Nginx -->|"Serves Static or Proxy to"| ReactContainer
    Nginx -->|"Proxy /api/* to"| BackendContainer
    ReactContainer -->|"REST API Calls (JWT)"| BackendContainer
    BackendContainer -->|"SQL Queries"| Postgres
    BackendContainer -->|"Publish Tasks"| Redis
    Worker -->|"Consume Tasks"| Redis
    Worker -->|"DB Operations"| Postgres
    Flower -->|"Monitor"| Redis
    DockerCompose --> Nginx
    DockerCompose --> ReactContainer
    DockerCompose --> BackendContainer
    DockerCompose --> Postgres
    DockerCompose --> Redis
    DockerCompose --> Worker
    DockerCompose --> Flower
    DockerCompose --> Actions
    DockerCompose --> Scripts

    %% Legend
    subgraph "Legend"
        LF["Frontend"]:::frontend
        LB["Backend"]:::backend
        LD["Database"]:::database
        LM["Broker/Worker"]:::broker
        LP["Proxy"]:::proxy
        LI["Infra"]:::infra
    end

    %% Styles
    classDef frontend fill:#C6DBFE,stroke:#3182BD,stroke-width:1px
    classDef backend fill:#C7E9C0,stroke:#31A354,stroke-width:1px
    classDef database fill:#FDD0A2,stroke:#E6550D,stroke-width:1px
    classDef broker fill:#FCAE91,stroke:#DE2D26,stroke-width:1px
    classDef proxy fill:#DADAEB,stroke:#6A51A3,stroke-width:1px
    classDef infra fill:#E5E5E5,stroke:#636363,stroke-width:1px
    classDef external fill:#FFFFFF,stroke:#000000,stroke-width:1px,stroke-dasharray: 5 5
```
