# chiyuliu67/gitdiagram architecture

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

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

## Overview

##### Project type and purpose
- The frontend is built with Next.js (TypeScript + Tailwind + ShadCN), and the backend is a Python FastAPI service. A PostgreSQL database (via Drizzle ORM) stores any needed state or caches. The system also integrates with external services (OpenAI o4-mini, GitHub API, PostHog analytics).

##### File structure
- Top-level directories:
- backend/ – Dockerfile, FastAPI app modules (core, routers, services, utils), Nginx config, deploy scripts
- src/ – Next.js app, React components, hooks, lib, server/db, styles
- public/ – static assets
- config files: docker-compose.yml, drizzle.config.ts, next.config.js, tsconfig.json, .env.example, GitHub Actions under .github/workflows
- backend/app/routers contains two main API endpoints: /generate and /modify
- backend/app/services contains connectors to Claude/OpenAI, GitHub, and rate-limiter logic
- src/app holds Next.js page routes (dynamic [username]/[repo]) and Server Actions
- src/server/db/schema.ts defines your PostgreSQL tables with Drizzle ORM

##### Inspect the README for architectural insights
- Confirms stack: Next.js frontend on Vercel, Python FastAPI backend on EC2 (Docker + Nginx), PostgreSQL local or containerized, CI/CD via GitHub Actions, analytics via PostHog and Api-Analytics.
- Highlights that most “processing” is done via prompt engineering in backend/app/prompts.py.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Browser["Client Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend (Vercel)" 
        direction TB
        NextApp["Next.js Frontend\n(src/app)"]:::frontend
        ReactComps["React Components\n(src/components)"]:::frontend
        Styles["Global Styles\n(src/styles/globals.css\ntailwind.config.ts)"]:::frontend
        ServerActions["Next.js Server Actions\n(src/app/_actions)"]:::frontend
        FetchUtil["Backend Fetch Utility\n(src/lib/fetch-backend.ts)"]:::frontend
        Hooks1["useDiagram Hook\n(src/hooks/useDiagram.ts)"]:::frontend
        Hooks2["useStarReminder Hook\n(src/hooks/useStarReminder.tsx)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Service (EC2)" 
        direction TB
        Nginx["Nginx Reverse Proxy\n(backend/nginx/api.conf)"]:::infra
        Main["FastAPI Entrypoint\n(backend/app/main.py)"]:::backend
        Routers["Routers\n(generate.py, modify.py)"]:::backend
        Limiter["Rate Limiter\n(core/limiter.py)"]:::backend
        Prompts["Prompt Pipelines\n(app/prompts.py)"]:::backend
        subgraph "AI & GitHub Services"
            direction TB
            GitHubSvc["GitHub API Service\n(services/github_service.py)"]:::backend
            OpenAISvc["OpenAI o4-mini Service\n(services/o4_mini_openai_service.py)"]:::backend
            O1Svc["o1 Mini Service\n(services/o1_mini_openai_service.py)"]:::backend
            O3Svc["o3 Mini OpenAI\n(services/o3_mini_openai_service.py)"]:::backend
            RouterSvc["o3 Mini OpenRouter\n(services/o3_mini_openrouter_service.py)"]:::backend
            ClaudeSvc["Claude Service\n(services/claude_service.py)"]:::backend
        end
        Formatter["Message Formatter\n(utils/format_message.py)"]:::backend
    end

    %% Database Layer
    subgraph "Database (PostgreSQL)" 
        direction TB
        Schema["Drizzle ORM Schema\n(src/server/db/schema.ts)"]:::db
        DrizzleCfg["Drizzle Config\n(drizzle.config.ts)"]:::db
    end

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

    %% Infrastructure
    subgraph "Containerization & Deployment"
        direction TB
        DockerCompose["Docker Compose\n(docker-compose.yml)"]:::infra
        Dockerfile["Backend Dockerfile\n(backend/Dockerfile)"]:::infra
        Entrypoint["entrypoint.sh\n(backend/entrypoint.sh)"]:::infra
        DBStart["DB Init Script\n(start-database.sh)"]:::infra
        Env["Env Templates\n(.env.example)"]:::infra
        CI["GitHub Actions\n(.github/workflows/deploy.yml)"]:::infra
    end

    %% Flows
    Browser -->|"HTTP GET/POST"| NextApp
    NextApp -->|uses| ReactComps
    NextApp -->|applies| Styles
    NextApp -->|calls| ServerActions
    ServerActions -->|fetch| FetchUtil
    FetchUtil -->|HTTP POST /generate| Main
    FetchUtil -->|HTTP POST /modify| Main

    Main -->|routes to| Routers
    Routers -->|uses| Limiter
    Routers -->|calls| Prompts
    Routers -->|calls| GitHubSvc
    Routers -->|calls| OpenAISvc
    Routers -->|calls| O1Svc
    Routers -->|calls| O3Svc
    Routers -->|calls| RouterSvc
    Routers -->|calls| ClaudeSvc
    Prompts -->|formats via| Formatter

    Main -->|queries| Schema
    Main -->|migrates via| DrizzleCfg

    Main -->|behind| Nginx
    Nginx -->|proxy to| Main

    Main -->|analytics| ApiAnalytics
    NextApp -->|analytics| PostHog

    Main -->|REST calls| OpenAI
    Main -->|REST calls| GitHubAPI

    DockerCompose --> Dockerfile
    DockerCompose --> Entrypoint
    DockerCompose --> DBStart
    DockerCompose --> Nginx
    DockerCompose --> Main
    DockerCompose --> Schema

    CI -->|deploy frontend| NextApp
    CI -->|deploy backend| DockerCompose

    %% Click events
    click NextApp "https://github.com/chiyuliu67/gitdiagram/tree/main/src/app"
    click ReactComps "https://github.com/chiyuliu67/gitdiagram/tree/main/src/components"
    click Styles "https://github.com/chiyuliu67/gitdiagram/blob/main/src/styles/globals.css"
    click Styles "https://github.com/chiyuliu67/gitdiagram/blob/main/tailwind.config.ts"
    click ServerActions "https://github.com/chiyuliu67/gitdiagram/tree/main/src/app/_actions"
    click FetchUtil "https://github.com/chiyuliu67/gitdiagram/blob/main/src/lib/fetch-backend.ts"
    click Hooks1 "https://github.com/chiyuliu67/gitdiagram/blob/main/src/hooks/useDiagram.ts"
    click Hooks2 "https://github.com/chiyuliu67/gitdiagram/blob/main/src/hooks/useStarReminder.tsx"
    click Schema "https://github.com/chiyuliu67/gitdiagram/blob/main/src/server/db/schema.ts"
    click DrizzleCfg "https://github.com/chiyuliu67/gitdiagram/blob/main/drizzle.config.ts"
    click Main "https://github.com/chiyuliu67/gitdiagram/blob/main/backend/app/main.py"
    click Routers "https://github.com/chiyuliu67/gitdiagram/blob/main/backend/app/routers/generate.py"
    click Routers "https://github.com/chiyuliu67/gitdiagram/blob/main/backend/app/routers/modify.py"
    click Limiter "https://github.com/chiyuliu67/gitdiagram/blob/main/backend/app/core/limiter.py"
    click Prompts "https://github.com/chiyuliu67/gitdiagram/blob/main/backend/app/prompts.py"
    click GitHubSvc "https://github.com/chiyuliu67/gitdiagram/blob/main/backend/app/services/github_service.py"
    click OpenAISvc "https://github.com/chiyuliu67/gitdiagram/blob/main/backend/app/services/o4_mini_openai_service.py"
    click O1Svc "https://github.com/chiyuliu67/gitdiagram/blob/main/backend/app/services/o1_mini_openai_service.py"
    click O3Svc "https://github.com/chiyuliu67/gitdiagram/blob/main/backend/app/services/o3_mini_openai_service.py"
    click RouterSvc "https://github.com/chiyuliu67/gitdiagram/blob/main/backend/app/services/o3_mini_openrouter_service.py"
    click ClaudeSvc "https://github.com/chiyuliu67/gitdiagram/blob/main/backend/app/services/claude_service.py"
    click Formatter "https://github.com/chiyuliu67/gitdiagram/blob/main/backend/app/utils/format_message.py"
    click Nginx "https://github.com/chiyuliu67/gitdiagram/blob/main/backend/nginx/api.conf"
    click DockerCompose "https://github.com/chiyuliu67/gitdiagram/blob/main/docker-compose.yml"
    click Dockerfile "https://github.com/chiyuliu67/gitdiagram/tree/main/backend/Dockerfile"
    click Entrypoint "https://github.com/chiyuliu67/gitdiagram/blob/main/backend/entrypoint.sh"
    click DBStart "https://github.com/chiyuliu67/gitdiagram/blob/main/start-database.sh"
    click Env "https://github.com/chiyuliu67/gitdiagram/blob/main/.env.example"
    click CI "https://github.com/chiyuliu67/gitdiagram/blob/main/.github/workflows/deploy.yml"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef backend fill:#D5F5E3,stroke:#145A32,color:#0B5345
    classDef db fill:#F9E79F,stroke:#B7950B,color:#7D6608
    classDef external fill:#E8DAEF,stroke:#6C3483,color:#512E5F
    classDef infra fill:#F2D7D5,stroke:#C0392B,color:#78281F
```
