# naresh5021/gitdiagram architecture

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

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

## Overview

##### Project type and purpose
- Frontend built in Next.js + TypeScript + Tailwind, backend in Python FastAPI, persisting data in PostgreSQL via Drizzle ORM, and orchestrating calls to OpenAI/Anthropic & GitHub APIs.

##### File structure
- Top-level:
- backend/ ─ contains the FastAPI service, Dockerfile, entrypoint, rate-limit logic, nginx proxy, and shell scripts for deployment and DB setup
- src/ ─ Next.js app with React components, server actions (cache, GitHub, repo fetch), custom hooks, UI library under components/ui, global styles, env.js
- src/server/db/ ─ Drizzle ORM schema and connection code for Postgres
- docker-compose.yml & start-database.sh ─ define multi-container orchestration (FastAPI, Postgres, nginx)
- config files (tsconfig.json, next.config.js, drizzle.config.ts) and CI/CD workflows (.github/)
- Patterns:
- Layered architecture in the backend: routers → services → utils
- Separation of concerns in frontend: page.tsx for layouts, _actions for server-side operations, hooks for client caches
- API gateway/proxy via nginx

##### Extract insights from README
- Architecture: Frontend (Vercel) ↔ Backend (EC2) behind nginx
- Database: PostgreSQL + Drizzle ORM
- AI: OpenAI o4-mini (and Claude previously) consumed via a services layer
- CI/CD: GitHub Actions, Analytics with PostHog & Api-Analytics

##### Main components & interactions
a. Components:
- User Browser (React UI)
- Next.js Frontend:
– Client-side pages & components
– Server Actions/API Routes (src/app/_actions)
- API Gateway/Reverse Proxy (nginx in backend/nginx)
- FastAPI Backend:
– Routers (generate, modify)
– Core (rate limiter, prompts pipeline)
– Services (openai, claude, openrouter, GitHub)
– Utils (message formatting)
- PostgreSQL Database (Drizzle ORM)
- External services:
– OpenAI/Anthropic APIs
– GitHub REST API
- CI/CD & Analytics (GitHub Actions, PostHog)
b. Relationships & data flow:
1. Browser → Next.js Frontend (user inputs repo URL)
2. Frontend Server Action → Backend API (POST /generate) via nginx
3. FastAPI Router enforces rate limits → Core pipelines (prompts.py)
4. Core calls Service layer:
– GitHub Service fetches file tree & README
5. FastAPI stores any persistent data in Postgres via Drizzle
c. Architectural patterns & principles:
- Layered service architecture in backend (Router → Service → Utils)
- Strict frontend/backend separation with API boundary
- Stateless backend behind nginx, stateful Postgres for rate data or caching
d. Key technologies: Next.js, React, Tailwind, FastAPI, Python, Docker, nginx, PostgreSQL, Drizzle ORM, OpenAI o4-mini, GitHub API

##### Detail
- Layering (e.g., Router → Service → Utils → External)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Zone
    subgraph "Client" 
        subgraph "UI Components" 
            A1["ActionButton"]:::client
            A2["MermaidDiagram"]:::client
            A3["Header"]:::client
            A4["Footer"]:::client
        end
        subgraph "Pages & Layouts"
            B1["page.tsx"]:::client
            B2["[username]/[repo]/page.tsx"]:::client
            B3["layout.tsx"]:::client
            B4["providers.tsx"]:::client
        end
        subgraph "Server Actions/API Routes"
            C1["cache.ts"]:::client
            C2["github.ts"]:::client
            C3["repo.ts"]:::client
        end
        subgraph "Custom Hooks"
            D1["useDiagram.ts"]:::client
            D2["useStarReminder.tsx"]:::client
        end
    end

    %% Server Zone
    subgraph "Server"
        subgraph "NGINX/API Gateway" 
            E1["api.conf"]:::server
        end
        subgraph "FastAPI Backend"
            subgraph "Entrypoint & Config"
                F1["main.py"]:::server
                F2["entrypoint.sh"]:::server
                F3["Dockerfile"]:::server
            end
            subgraph "Routers"
                G1["generate.py"]:::server
                G2["modify.py"]:::server
            end
            subgraph "Core Logic"
                H1["limiter.py"]:::server
                H2["prompts.py"]:::server
            end
            subgraph "Service Layer"
                I1["claude_service.py"]:::server
                I2["github_service.py"]:::server
                I3["o1_mini_openai_service.py"]:::server
                I4["o3_mini_openai_service.py"]:::server
                I5["o3_mini_openrouter_service.py"]:::server
                I6["o4_mini_openai_service.py"]:::server
            end
            subgraph "Utilities"
                J1["format_message.py"]:::server
            end
        end
    end

    %% Database
    subgraph "Database"
        K1["PostgreSQL"]:::database
        subgraph "Drizzle ORM"
            L1["schema.ts"]:::database
            L2["index.ts"]:::database
            L3["drizzle.config.ts"]:::database
        end
    end

    %% External Services
    subgraph "External Services"
        M1["OpenAI / Anthropic APIs"]:::external
        M2["GitHub REST API"]:::external
    end

    %% Client to Server flows
    A1 -->|uses| B1
    B1 -->|renders UI| A2
    B1 -->|calls| C1
    B2 -->|calls| C2
    B2 -->|calls| C3
    D1 -.->|manages cache| C1
    D2 -.->|reminder logic| A2

    %% Server ingress
    C1 -->|HTTP POST /generate| E1
    C2 -->|HTTP POST /generate| E1
    E1 -->|proxy to| F1

    %% Backend flow
    F1 -->|routes to| G1
    F1 -->|routes to| G2
    G1 -->|rate limit| H1
    G1 -->|process prompt| H2
    H2 -->|call| I2
    H2 -->|call| I1
    H2 -->|call| I3
    H2 -->|call| I4
    H2 -->|call| I5
    H2 -->|call| I6
    I2 -->|fetch repo| M2
    I1 -->|ai completion| M1
    I3 -->|ai completion| M1
    I4 -->|ai completion| M1
    I5 -->|ai completion| M1
    I6 -->|ai completion| M1
    G1 -->|store data| K1
    J1 -->|format messages| H2
    G1 -->|response JSON| F1
    F1 -->|HTTP 200 JSON| E1

    %% Server to Client response
    E1 -->|JSON response| C1
    C1 -->|diagram data| B1
    B1 -->|renders| A2

    %% Database & Drizzle
    K1 -->|SQL queries| L1
    K1 -->|connection| L2
    L3 -->|config| L2

    %% Click Events
    click A1 "https://github.com/naresh5021/gitdiagram/blob/main/src/components/action-button.tsx"
    click A2 "https://github.com/naresh5021/gitdiagram/blob/main/src/components/mermaid-diagram.tsx"
    click A3 "https://github.com/naresh5021/gitdiagram/blob/main/src/components/header.tsx"
    click A4 "https://github.com/naresh5021/gitdiagram/blob/main/src/components/footer.tsx"
    click B1 "https://github.com/naresh5021/gitdiagram/blob/main/src/app/page.tsx"
    click B2 "https://github.com/naresh5021/gitdiagram/blob/main/src/app/[username]/[repo]/page.tsx"
    click B3 "https://github.com/naresh5021/gitdiagram/blob/main/src/app/layout.tsx"
    click B4 "https://github.com/naresh5021/gitdiagram/blob/main/src/app/providers.tsx"
    click C1 "https://github.com/naresh5021/gitdiagram/blob/main/src/app/_actions/cache.ts"
    click C2 "https://github.com/naresh5021/gitdiagram/blob/main/src/app/_actions/github.ts"
    click C3 "https://github.com/naresh5021/gitdiagram/blob/main/src/app/_actions/repo.ts"
    click D1 "https://github.com/naresh5021/gitdiagram/blob/main/src/hooks/useDiagram.ts"
    click D2 "https://github.com/naresh5021/gitdiagram/blob/main/src/hooks/useStarReminder.tsx"
    click E1 "https://github.com/naresh5021/gitdiagram/blob/main/backend/nginx/api.conf"
    click F1 "https://github.com/naresh5021/gitdiagram/blob/main/backend/app/main.py"
    click F2 "https://github.com/naresh5021/gitdiagram/blob/main/backend/entrypoint.sh"
    click F3 "https://github.com/naresh5021/gitdiagram/tree/main/backend/Dockerfile"
    click G1 "https://github.com/naresh5021/gitdiagram/blob/main/backend/app/routers/generate.py"
    click G2 "https://github.com/naresh5021/gitdiagram/blob/main/backend/app/routers/modify.py"
    click H1 "https://github.com/naresh5021/gitdiagram/blob/main/backend/app/core/limiter.py"
    click H2 "https://github.com/naresh5021/gitdiagram/blob/main/backend/app/prompts.py"
    click I1 "https://github.com/naresh5021/gitdiagram/blob/main/backend/app/services/claude_service.py"
    click I2 "https://github.com/naresh5021/gitdiagram/blob/main/backend/app/services/github_service.py"
    click I3 "https://github.com/naresh5021/gitdiagram/blob/main/backend/app/services/o1_mini_openai_service.py"
    click I4 "https://github.com/naresh5021/gitdiagram/blob/main/backend/app/services/o3_mini_openai_service.py"
    click I5 "https://github.com/naresh5021/gitdiagram/blob/main/backend/app/services/o3_mini_openrouter_service.py"
    click I6 "https://github.com/naresh5021/gitdiagram/blob/main/backend/app/services/o4_mini_openai_service.py"
    click J1 "https://github.com/naresh5021/gitdiagram/blob/main/backend/app/utils/format_message.py"
    click L1 "https://github.com/naresh5021/gitdiagram/blob/main/src/server/db/schema.ts"
    click L2 "https://github.com/naresh5021/gitdiagram/blob/main/src/server/db/index.ts"
    click L3 "https://github.com/naresh5021/gitdiagram/blob/main/drizzle.config.ts"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#000
    classDef server fill:#D0FFD8,stroke:#000
    classDef external fill:#FFE4B5,stroke:#000
    classDef database fill:#E0D0FF,stroke:#000
```
