# mdsami/gitdiagram architecture

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

- Interactive diagram: https://gitdiagram.com/mdsami/gitdiagram
- Repository: https://github.com/mdsami/gitdiagram

## Overview

##### Project type and purpose
- The frontend is built in Next.js (TypeScript + Tailwind + ShadCN), and the backend is a FastAPI (Python) service. A PostgreSQL database (via Drizzle ORM) stores any necessary metadata, rate-limit tracking, or user tokens.

##### File structure
- **Top-level directories & files**
- `src/` → Next.js application (pages, server actions, React components, hooks, styles)
- `backend/` → FastAPI application (routers, services, core utilities, Docker, Nginx config)
- `server/db/` under `src/` → Drizzle ORM schema and database client for Next.js server actions
- `docker-compose.yml`, `start-database.sh` → orchestrate backend + Postgres locally
- Config files: `next.config.js`, `tailwind.config.ts`, `drizzle.config.ts`, `.env.example`, GitHub CI (`.github/workflows/deploy.yml`)
- **Patterns & Layers**
- Frontend “Server Actions” in Next.js call backend through REST.
- Backend organizes logic into routers (`generate.py`, `modify.py`), service classes (AI adapters, GitHub integration), core utils (rate limiter, formatters).
- Reverse proxy (Nginx) sits in front of FastAPI in Docker.
- Database migrations and client setups live in `server/db`.

##### Key insights from README
- Tech stack overview, deployment targets (Vercel for frontend, EC2 + Docker for backend).
- External integrations: OpenAI o4-mini (and other AI services), GitHub API, PostHog analytics, Api-Analytics.
- Self-hosting instructions reveal Docker + docker-compose orchestration and Drizzle ORM usage.

a. Main Components
- **User & Browser UI**: The Next.js React app (pages under `src/app/`)
- **Frontend Data Fetch/Server Actions**: Custom hooks (`useDiagram.ts`) and REST fetches (`src/lib/fetch-backend.ts`)
- **Backend API**: FastAPI application (routers & services) behind Nginx reverse proxy in Docker
- **Database**: PostgreSQL container managed via Drizzle ORM
- **AI Providers**: OpenAI o4-mini, Claude, custom OpenRouter endpoints
- **GitHub Service**: GitHub REST API calls for repo trees and file contents
- **Analytics**: PostHog & Api-Analytics (external)
- **CI/CD & Deployment**: GitHub Actions → Vercel (frontend) & EC2 (backend Docker)

b. Component Interactions
- Browser ↔ Next.js frontend (user clicks, navigates, triggers server actions)
- Frontend → FastAPI endpoints (`/generate`, `/modify`) via HTTP
- FastAPI → PostgreSQL (Drizzle ORM) for persisting rate-limits or tokens
- FastAPI → AI Provider services (via HTTP) for prompt processing
- FastAPI → GitHub API to fetch file trees and README content
- Analytics events flow from both frontend and backend to PostHog/Api-Analytics

c. Architectural Patterns & Principles
- **Layered architecture**: UI → API → Services → Data
- **Service abstraction**: One service class per external API (e.g., `claude_service.py`, `github_service.py`)
- **Rate limiting**: Centralized limiter in `core/limiter.py`
- **Infrastructure as code**: Dockerfiles, Compose, Nginx scripts, scripts for DB initialization
- **Server Actions**: Next.js’s experimental full-stack pattern

d. Key Technologies & Frameworks
- Frontend: Next.js, React Server Actions, TypeScript, Tailwind CSS, ShadCN UI components
- Backend: FastAPI, Uvicorn, Python 3.x, Pydantic, asyncio
- Data: PostgreSQL, Drizzle ORM (TypeScript)
- AI: OpenAI's o4-mini, Anthropic/Claude, mini-openrouter clients
- DevOps: Docker, docker-compose, Nginx, GitHub Actions, Vercel, AWS EC2

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Next.js Frontend" 
        direction TB
        UI["UI Components"]:::frontend
        Components["React Components"]:::frontend
        Styles["Global Styles"]:::frontend
        Layout["App Layout"]:::frontend
        Page["App Page"]:::frontend
        subgraph "Data & Actions"
            direction TB
            CacheAction["cache Actions"]:::frontend
            GitHubAction["GitHub Actions"]:::frontend
            RepoAction["Repo Actions"]:::frontend
            UseDiagram["useDiagram Hook"]:::frontend
            FetchBackend["fetch-backend"]:::frontend
        end
    end

    %% Backend Layer
    subgraph "FastAPI Backend + Nginx" 
        direction TB
        subgraph "Routers" 
            direction TB
            MainPy["main.py"]:::backend
            GeneratePy["generate.py"]:::backend
            ModifyPy["modify.py"]:::backend
        end
        subgraph "Services"
            direction TB
            ClaudeService["claude_service.py"]:::backend
            GitHubService["github_service.py"]:::backend
            O1Service["o1_mini_openai_service.py"]:::backend
            O3Service1["o3_mini_openai_service.py"]:::backend
            O3Router["o3_mini_openrouter_service.py"]:::backend
            O4Service["o4_mini_openai_service.py"]:::backend
        end
        subgraph "Core Utils"
            direction TB
            Limiter["limiter.py"]:::backend
            Formatter["format_message.py"]:::backend
        end
        Nginx["Nginx Reverse Proxy"]:::infra
        DockerConfig["Docker & Compose"]:::infra
    end

    %% Database
    PostgreSQL["PostgreSQL (Drizzle)"]:::database

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI o4-mini"]:::external
        ClaudeExt["Anthropic Claude"]:::external
        GitHubAPI["GitHub API"]:::external
        PostHog["PostHog Analytics"]:::external
        ApiAnalytics["Api-Analytics"]:::external
    end

    %% CI/CD
    CI["GitHub Actions CI/CD"]:::external

    %% Connections
    UI -->|"renders"| Components
    UI --> Styles
    UI --> Layout
    UI --> Page
    Page -->|uses| CacheAction
    Page -->|uses| GitHubAction
    Page -->|uses| RepoAction
    CacheAction -->|calls| FetchBackend
    GitHubAction -->|calls| FetchBackend
    RepoAction -->|calls| FetchBackend
    UseDiagram -->|hooks into| Page
    FetchBackend -->|"HTTP POST /generate"| GeneratePy
    FetchBackend -->|"HTTP POST /modify"| ModifyPy
    GeneratePy -->|"calls"| ClaudeService
    GeneratePy -->|"calls"| GitHubService
    GeneratePy -->|"uses"| Limiter
    GeneratePy -->|"DB query"| PostgreSQL
    ModifyPy -->|"calls"| O1Service
    ModifyPy -->|"calls"| O3Service1
    ModifyPy -->|"calls"| O3Router
    ModifyPy -->|"calls"| O4Service
    ModifyPy -->|"uses"| Formatter
    ModifyPy -->|"DB query"| PostgreSQL
    MainPy --> GeneratePy
    MainPy --> ModifyPy
    Nginx --> MainPy
    DockerConfig --> Nginx
    DockerConfig --> MainPy
    PostgreSQL -->|managed by| DockerConfig
    GeneratePy -->|HTTP| OpenAI
    GeneratePy -->|HTTP| GitHubAPI
    GeneratePy -->|HTTP| ClaudeExt
    GeneratePy -->|HTTP| ApiAnalytics
    GeneratePy -->|HTTP| PostHog
    ModifyPy -->|HTTP| OpenAI
    ModifyPy -->|HTTP| GitHubAPI
    ModifyPy -->|HTTP| ApiAnalytics
    ModifyPy -->|HTTP| PostHog
    UI -->|analytics events| PostHog
    GeneratePy -->|analytics events| ApiAnalytics
    CI -->|deploys frontend| UI
    CI -->|deploys backend| DockerConfig

    %% Click Events
    click UI "https://github.com/mdsami/gitdiagram/tree/main/src/app/"
    click Components "https://github.com/mdsami/gitdiagram/tree/main/src/components/"
    click Styles "https://github.com/mdsami/gitdiagram/blob/main/src/styles/globals.css"
    click Layout "https://github.com/mdsami/gitdiagram/blob/main/src/app/layout.tsx"
    click Page "https://github.com/mdsami/gitdiagram/blob/main/src/app/page.tsx"
    click CacheAction "https://github.com/mdsami/gitdiagram/blob/main/src/app/_actions/cache.ts"
    click GitHubAction "https://github.com/mdsami/gitdiagram/blob/main/src/app/_actions/github.ts"
    click RepoAction "https://github.com/mdsami/gitdiagram/blob/main/src/app/_actions/repo.ts"
    click UseDiagram "https://github.com/mdsami/gitdiagram/blob/main/src/hooks/useDiagram.ts"
    click FetchBackend "https://github.com/mdsami/gitdiagram/blob/main/src/lib/fetch-backend.ts"
    click MainPy "https://github.com/mdsami/gitdiagram/blob/main/backend/app/main.py"
    click GeneratePy "https://github.com/mdsami/gitdiagram/blob/main/backend/app/routers/generate.py"
    click ModifyPy "https://github.com/mdsami/gitdiagram/blob/main/backend/app/routers/modify.py"
    click ClaudeService "https://github.com/mdsami/gitdiagram/blob/main/backend/app/services/claude_service.py"
    click GitHubService "https://github.com/mdsami/gitdiagram/blob/main/backend/app/services/github_service.py"
    click O1Service "https://github.com/mdsami/gitdiagram/blob/main/backend/app/services/o1_mini_openai_service.py"
    click O3Service1 "https://github.com/mdsami/gitdiagram/blob/main/backend/app/services/o3_mini_openai_service.py"
    click O3Router "https://github.com/mdsami/gitdiagram/blob/main/backend/app/services/o3_mini_openrouter_service.py"
    click O4Service "https://github.com/mdsami/gitdiagram/blob/main/backend/app/services/o4_mini_openai_service.py"
    click Limiter "https://github.com/mdsami/gitdiagram/blob/main/backend/app/core/limiter.py"
    click Formatter "https://github.com/mdsami/gitdiagram/blob/main/backend/app/utils/format_message.py"
    click PostgreSQL "https://github.com/mdsami/gitdiagram/blob/main/src/server/db/index.ts"
    click PostgreSQL "https://github.com/mdsami/gitdiagram/blob/main/src/server/db/schema.ts"
    click PostgreSQL "https://github.com/mdsami/gitdiagram/blob/main/drizzle.config.ts"
    click PostgreSQL "https://github.com/mdsami/gitdiagram/blob/main/start-database.sh"
    click DockerConfig "https://github.com/mdsami/gitdiagram/blob/main/docker-compose.yml"
    click DockerConfig "https://github.com/mdsami/gitdiagram/tree/main/backend/Dockerfile"
    click Nginx "https://github.com/mdsami/gitdiagram/blob/main/backend/nginx/api.conf"
    click Nginx "https://github.com/mdsami/gitdiagram/blob/main/backend/nginx/setup_nginx.sh"
    click CI "https://github.com/mdsami/gitdiagram/blob/main/.github/workflows/deploy.yml"

    %% Styles
    classDef frontend fill:#cfe2ff,stroke:#0366d6,color:#0366d6
    classDef backend fill:#ffe5b4,stroke:#d97706,color:#d97706
    classDef database fill:#d1e7dd,stroke:#0f5132,color:#0f5132
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef infra fill:#f8d7da,stroke:#842029,color:#842029
```
