# vintasoftware/nextjs-fastapi-template architecture

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

- Interactive diagram: https://gitdiagram.com/vintasoftware/nextjs-fastapi-template
- Repository: https://github.com/vintasoftware/nextjs-fastapi-template

## Overview

##### Main Components
- Backend Service: Represented by the “fastapi_backend” directory. Highlight key elements such as:
– API endpoints (located under fastapi_backend/api and fastapi_backend/app/routes)
– Database interactions (files under fastapi_backend/app/database, Alembic migrations, and models)
– Business logic and utilities (modules like fastapi_backend/app/utils, users, email, etc.)
– Commands and tooling such as the OpenAPI schema generation (under fastapi_backend/commands)
- Frontend Service: Represented by the “nextjs-frontend” directory. Key aspects include:
– Pages and components (see directories like nextjs-frontend/app, nextjs-frontend/components)
– OpenAPI client integration (under nextjs-frontend/app/openapi-client)
– TypeScript with Zod validations (illustrate the integration with generated types)
- Database: Although not directly present in the file tree, the README references PostgreSQL and Docker Compose setups. Also include information on migrations (Alembic scripts) and configurations.
- External Services and Tools:
– Docker & Docker Compose: Explain how Docker is used to containerize both the frontend and backend as well as supporting services (database, MailHog for email testing).
– CI/CD Workflows: GitHub Actions workflows located under “.github/workflows” for continuous integration and deployment.
– Pre-commit Hooks: Illustrate the local and Docker-based pre-commit configurations in enforcing code quality.
– Hot Reload & File Watching: Show that backend uses Python-based file watchers (e.g., Watchdog) and the frontend uses Chokidar to trigger updates and schema regeneration.
– Email Service: Use of MailHog for local email testing.

##### Relationships and Interactions
– Backend generates the openapi.json either manually or automatically.
– The generated OpenAPI schema is then used by the frontend client (in nextjs-frontend/app/openapi-client) to maintain type safety.
- Database’s Role:
- CI/CD Pipeline:
– Represent GitHub Actions as the orchestrator that, upon code push, triggers builds and deployments.
- Demonstrate integration with Docker:
– Use containers for backend, frontend, database, and MailHog. Illustrate connections among these containers and the local development workflow via docker-compose.

##### Architectural Patterns and Design Principles
- Modular Design: Both the backend and frontend are well separated into domain-specific subfolders (e.g., API routes, models, components).
- Service Separation: Clearly emphasize the decoupling between frontend and backend, a typical full-stack pattern.
- Type Safety & Client Generation: Underline the use of Zod and OpenAPI for end-to-end type safety and a self-updating client contract.
- Containerization Principle: Emphasize the use of Docker and the consistency it brings to development, testing, and production environments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% FastAPI Backend
    subgraph "FastAPI Backend"
        BA1["API Endpoints (fastapi_backend/api)"]:::backend
        BA2["API Routes (fastapi_backend/app/routes)"]:::backend
        BA3["Database Module (fastapi_backend/app/database)"]:::backend
        BA4["Models (fastapi_backend/app/models.py)"]:::backend
        BA5["Alembic Config (fastapi_backend/alembic.ini)"]:::backend
        BA6["Alembic Migrations (fastapi_backend/alembic_migrations)"]:::backend
        BA7["Utilities (fastapi_backend/app/utils.py)"]:::backend
        BA8["Users (fastapi_backend/app/users.py)"]:::backend
        BA9["Email Logic (fastapi_backend/app/email.py)"]:::backend
        BA10["Email Templates (fastapi_backend/app/email_templates)"]:::backend
        BA11["OpenAPI Schema Generator (fastapi_backend/commands/generate_openapi_schema.py)"]:::backend
        BW["Backend File Watcher (fastapi_backend/watcher.py)"]:::backend
    end

    %% Next.js Frontend
    subgraph "Next.js Frontend"
        FA1["Pages & Components (nextjs-frontend/app)"]:::frontend
        FA2["OpenAPI Client (nextjs-frontend/app/openapi-client)"]:::frontend
        FA3["UI Components (nextjs-frontend/components)"]:::frontend
        FA4["Public Assets (nextjs-frontend/public)"]:::frontend
        FW["Frontend File Watcher (nextjs-frontend/watcher.js)"]:::frontend
    end

    %% DevOps & Tools
    subgraph "DevOps & Tools"
        D1["Docker Compose (docker-compose.yml)"]:::devops
        D2["Backend Dockerfile (fastapi_backend/Dockerfile)"]:::devops
        D3["Frontend Dockerfile (nextjs-frontend/Dockerfile)"]:::devops
        CI["GitHub Actions (.github/workflows)"]:::devops
        PC["Pre-commit Config (.pre-commit-config.yaml & .pre-commit-config.docker.yaml)"]:::devops
        MH["MailHog Email Service"]:::devops
    end

    %% External Database
    DB["PostgreSQL Database"]:::database

    %% Interconnections between Frontend and Backend
    FA1 -->|"api_call"| BA1
    FA1 -->|"api_call"| BA2

    %% Database interactions from Backend API nodes
    BA1 -->|"db_query"| BA3
    BA1 -->|"db_query"| BA4
    BA1 -->|"db_query"| BA5
    BA1 -->|"db_query"| BA6
    BA2 -->|"db_query"| BA3
    BA2 -->|"db_query"| BA4
    BA2 -->|"db_query"| BA5
    BA2 -->|"db_query"| BA6

    %% Backend modules interacting with Database
    BA3 -->|"read/write"| DB
    BA4 -->|"read/write"| DB
    BA5 -->|"read/write"| DB
    BA6 -->|"read/write"| DB

    %% OpenAPI workflow: Schema generation to Frontend OpenAPI Client
    BA11 -->|"generates_schema"| FA2

    %% Email service integration
    BA9 -->|"triggers"| MH

    %% CI/CD triggers Docker builds
    CI --> D2
    CI --> D3
    CI --> D1
    PC --> CI

    %% File Watchers associated with their services
    BW --- BA1
    FW --- FA1

    %% Class Definitions
    classDef backend fill:#F9E79F,stroke:#000,stroke-width:1px;
    classDef frontend fill:#AED6F1,stroke:#000,stroke-width:1px;
    classDef devops fill:#F5B7B1,stroke:#000,stroke-width:1px;
    classDef database fill:#A9DFBF,stroke:#000,stroke-width:1px;

    %% Click Events for FastAPI Backend
    click BA1 "https://github.com/vintasoftware/nextjs-fastapi-template/tree/main/fastapi_backend/api"
    click BA2 "https://github.com/vintasoftware/nextjs-fastapi-template/tree/main/fastapi_backend/app/routes"
    click BA3 "https://github.com/vintasoftware/nextjs-fastapi-template/tree/main/fastapi_backend/app/database"
    click BA4 "https://github.com/vintasoftware/nextjs-fastapi-template/blob/main/fastapi_backend/app/models.py"
    click BA5 "https://github.com/vintasoftware/nextjs-fastapi-template/blob/main/fastapi_backend/alembic.ini"
    click BA6 "https://github.com/vintasoftware/nextjs-fastapi-template/tree/main/fastapi_backend/alembic_migrations"
    click BA7 "https://github.com/vintasoftware/nextjs-fastapi-template/blob/main/fastapi_backend/app/utils.py"
    click BA8 "https://github.com/vintasoftware/nextjs-fastapi-template/blob/main/fastapi_backend/app/users.py"
    click BA9 "https://github.com/vintasoftware/nextjs-fastapi-template/blob/main/fastapi_backend/app/email.py"
    click BA10 "https://github.com/vintasoftware/nextjs-fastapi-template/tree/main/fastapi_backend/app/email_templates"
    click BA11 "https://github.com/vintasoftware/nextjs-fastapi-template/blob/main/fastapi_backend/commands/generate_openapi_schema.py"
    click BW "https://github.com/vintasoftware/nextjs-fastapi-template/blob/main/fastapi_backend/watcher.py"

    %% Click Events for Next.js Frontend
    click FA1 "https://github.com/vintasoftware/nextjs-fastapi-template/tree/main/nextjs-frontend/app"
    click FA2 "https://github.com/vintasoftware/nextjs-fastapi-template/tree/main/nextjs-frontend/app/openapi-client"
    click FA3 "https://github.com/vintasoftware/nextjs-fastapi-template/tree/main/nextjs-frontend/components"
    click FA4 "https://github.com/vintasoftware/nextjs-fastapi-template/tree/main/nextjs-frontend/public"
    click FW "https://github.com/vintasoftware/nextjs-fastapi-template/blob/main/nextjs-frontend/watcher.js"

    %% Click Events for DevOps & Tools
    click D1 "https://github.com/vintasoftware/nextjs-fastapi-template/blob/main/docker-compose.yml"
    click D2 "https://github.com/vintasoftware/nextjs-fastapi-template/tree/main/fastapi_backend/Dockerfile"
    click D3 "https://github.com/vintasoftware/nextjs-fastapi-template/tree/main/nextjs-frontend/Dockerfile"
    click CI "https://github.com/vintasoftware/nextjs-fastapi-template/tree/main/.github/workflows"
    click PC "https://github.com/vintasoftware/nextjs-fastapi-template/blob/main/.pre-commit-config.yaml"
```
