# lc708/gitdiagram architecture

> Architecture diagram of the GitHub repository lc708/gitdiagram, 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/lc708/gitdiagram
- Repository: https://github.com/lc708/gitdiagram

## Overview

##### Project Type and Purpose
- It leverages prompt engineering (see the backend’s “prompts.py”) alongside AI services (OpenAI’s o3-mini and previously Claude 3.5 Sonnet) to process repository data.
- The project is full-stack with a Next.js/TypeScript frontend and a FastAPI/Python backend, and it also uses a PostgreSQL database (with Drizzle ORM).

##### File Structure
- Notice the clear separation between “backend” and “src”:
- The “backend” folder contains the Python FastAPI server with components such as routers (e.g., “generate.py”, “modify.py”), services (connecting to AI and GitHub APIs), configuration (nginx), and utility scripts.
- The “src” folder drives the frontend (Next.js) and includes directories like “app” with pages, actions, and server-side utilities, as well as “components” which have UI building blocks.
- Additionally, configuration files like “docker-compose.yml”, “Dockerfile”, “drizzle.config.ts”, and CI/CD configurations in “.github/workflows” indicate considerations for containerization, deployment, and continuous integration.

##### Core Components to Highlight
a. Frontend (Client-Side)
- Next.js application using TypeScript, Tailwind CSS, and ShadCN.

b. Backend (API & Processing Layer)
- Python FastAPI server providing REST endpoints to process incoming requests.
- Key modules include:
- Routers (e.g., “generate.py”, “modify.py”) – they handle API endpoints.
- Services (e.g., “claude_service.py”, “o1_mini_openai_service.py”, etc.) – manage integration with external AI services and GitHub.
- Prompts (in “prompts.py”) – contain prompt engineering logic for data extraction and analysis.
- Contains automation scripts (entrypoint.sh, deploy.sh) and an Nginx configuration to reverse-proxy requests.

c. Database
- PostgreSQL powered by Drizzle ORM as seen in “src/server/db” indicating the storage of processed data or user-requested information.
- Initialization and migrations are managed via the command “pnpm db:push” and a local “start-database.sh” script.

d. External and Integration Services
- GitHub APIs: For fetching repository structure and details.
- CI/CD & Deployment: Vercel for the frontend and EC2 for the backend, along with GitHub Actions for deployment pipelines.
- Optional analytics (PostHog, Api-Analytics) for tracking usage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    U["User (Browser)"]:::user

    %% Frontend Layer
    subgraph "Frontend (Next.js & TypeScript)"
        F1["Main App & Pages"]:::frontend
        F2["UI Components"]:::frontend
        F3["Styles (src/styles)"]:::frontend
        F4["next.config.js"]:::frontend
        F5["package.json"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (FastAPI & Python)"
        B1["API Entry Point (main.py)"]:::backend
        B2["Prompt Engineering (prompts.py)"]:::backend
        B3["Router: Generate (generate.py)"]:::backend
        B4["Router: Modify (modify.py)"]:::backend
        B5["Claude Service"]:::backend
        B6["Mini OpenAI Service (o1)"]:::backend
        B7["Mini OpenAI Service (o3)"]:::backend
        B8["OpenRouter Service"]:::backend
        B9["GitHub Service"]:::backend
        B10["Utility Scripts"]:::backend
    end

    %% Database Layer
    subgraph "Database (PostgreSQL with Drizzle ORM)"
        D1["DB Schema & Access (src/server/db)"]:::database
    end

    %% Deployment & Containerization Layer
    subgraph "Deployment & Containerization"
        DP1["Dockerfile"]:::deployment
        DP2["Docker Compose"]:::deployment
        DP3["Deployment Scripts"]:::deployment
        DP4["Nginx Setup"]:::deployment
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        CI1["GitHub Actions Workflow"]:::ci
    end

    %% External Services Layer
    subgraph "External Services"
        EX1["AI Services (o3-mini & Claude)"]:::external
        EX2["GitHub API"]:::external
    end

    %% Connections
    U -->|"uses"| F1

    %% Frontend internal connections (for clarity, grouping only)
    F1 --> F2
    F1 --> F3
    F1 --> F4
    F1 --> F5

    %% Frontend to Backend communication
    F1 -->|"API call"| B1

    %% Backend internal flow
    B1 -->|"processes"| B2
    B1 -->|"routes to"| B3
    B1 -->|"routes to"| B4

    %% Routers use services
    B3 -->|"calls"| B5
    B3 -->|"calls"| B6
    B4 -->|"calls"| B7
    B4 -->|"calls"| B8
    B4 -->|"calls"| B9
    B1 --> B10

    %% Backend interacts with External Services & Database
    B5 -->|"integrates"| EX1
    B6 -->|"integrates"| EX1
    B7 -->|"integrates"| EX1
    B8 -->|"integrates"| EX1
    B9 -->|"integrates"| EX2
    B1 -->|"stores data"| D1

    %% Deployment reverse proxy
    DP4 -->|"reverse proxies to"| B1

    %% Deployment connects to Backend and Database
    DP1 --> B1
    DP2 --> B1
    DP3 --> B1
    DP3 --> D1

    %% CI/CD deploys Deployment components
    CI1 --> DP1
    CI1 --> DP2
    CI1 --> DP3
    CI1 --> DP4

    %% Click events
    click F1 "https://github.com/lc708/gitdiagram/tree/main/src/app"
    click F2 "https://github.com/lc708/gitdiagram/tree/main/src/components"
    click F3 "https://github.com/lc708/gitdiagram/tree/main/src/styles"
    click F4 "https://github.com/lc708/gitdiagram/blob/main/next.config.js"
    click F5 "https://github.com/lc708/gitdiagram/blob/main/package.json"
    click B1 "https://github.com/lc708/gitdiagram/blob/main/backend/app/main.py"
    click B2 "https://github.com/lc708/gitdiagram/blob/main/backend/app/prompts.py"
    click B3 "https://github.com/lc708/gitdiagram/blob/main/backend/app/routers/generate.py"
    click B4 "https://github.com/lc708/gitdiagram/blob/main/backend/app/routers/modify.py"
    click B5 "https://github.com/lc708/gitdiagram/blob/main/backend/app/services/claude_service.py"
    click B6 "https://github.com/lc708/gitdiagram/blob/main/backend/app/services/o1_mini_openai_service.py"
    click B7 "https://github.com/lc708/gitdiagram/blob/main/backend/app/services/o3_mini_openai_service.py"
    click B8 "https://github.com/lc708/gitdiagram/blob/main/backend/app/services/o3_mini_openrouter_service.py"
    click B9 "https://github.com/lc708/gitdiagram/blob/main/backend/app/services/github_service.py"
    click B10 "https://github.com/lc708/gitdiagram/blob/main/backend/app/utils/format_message.py"
    click D1 "https://github.com/lc708/gitdiagram/tree/main/src/server/db"
    click DP1 "https://github.com/lc708/gitdiagram/tree/main/backend/Dockerfile"
    click DP2 "https://github.com/lc708/gitdiagram/blob/main/docker-compose.yml"
    click DP3 "https://github.com/lc708/gitdiagram/blob/main/backend/entrypoint.sh"
    click DP4 "https://github.com/lc708/gitdiagram/blob/main/backend/nginx/api.conf"
    click CI1 "https://github.com/lc708/gitdiagram/blob/main/.github/workflows/deploy.yml"

    %% Styles
    classDef user fill:#F4A460,stroke:#000,stroke-width:1px;
    classDef frontend fill:#ACE7EF,stroke:#000,stroke-width:1px;
    classDef backend fill:#F7B2AD,stroke:#000,stroke-width:1px;
    classDef database fill:#C1E1C1,stroke:#000,stroke-width:1px;
    classDef deployment fill:#FFD2A5,stroke:#000,stroke-width:1px;
    classDef ci fill:#D1C0E0,stroke:#000,stroke-width:1px;
    classDef external fill:#FCE883,stroke:#000,stroke-width:1px;
```
