# jabdy86/gitdiagram architecture

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

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

## Overview

##### Project type and purpose
- Frontend: Next.js + TypeScript + Tailwind CSS + ShadCN
- Database: PostgreSQL (Drizzle ORM)
- External services: OpenAI/Anthropic AI models, GitHub API

##### File structure
Top level:
- docker-compose.yml, start-database.sh – orchestrate local Docker services (backend, Postgres)
- backend/ – FastAPI service, routers, AI & GitHub service clients, Nginx config, Dockerfile, deploy/entrypoint scripts
- src/ – Next.js app with React components, server/db (Drizzle ORM), server actions, hooks, styles, public assets
- .github/workflows/deploy.yml – CI/CD for deploying frontend to Vercel and backend to EC2
- drizzle.config.ts – Drizzle ORM config for Postgres

Key patterns:
- Clear separation of concerns (frontend vs backend)
- Modular “services” in backend to encapsulate calls to each AI provider or GitHub API
- Server Actions in Next.js (`src/app/_actions`) for “backend-lite” operations (e.g., caching)
- PostHog + custom analytics instrumented in both layers

##### Main components
a. User’s Browser (UI)
– Next.js pages & React components
– UI state/hooks (useDiagram, useStarReminder)
– API calls via fetch-backend.ts / server actions

b. Frontend Hosting (Vercel)

c. Backend API (FastAPI)
– Routers: /generate, /modify
– Core rate-limiter
– Prompt pipeline (prompts.py)
– Services: anthropic/Claude, OpenAI variants, OpenRouter, GitHub service

d. Reverse Proxy (Nginx)

e. Database (PostgreSQL via Drizzle ORM)
– Usage logs, caching, rate-limit state

f. External Services
– OpenAI / Anthropic AI endpoints
– GitHub REST API
– Analytics (PostHog, Api-Analytics)

g. CI/CD (GitHub Actions)

##### Relationships & data flows
1) User interacts with Frontend UI → triggers HTTP request (REST or Server Action).
2) Frontend → Backend (via nginx reverse proxy) `/generate` or `/modify`.
3) Backend Router
– Applies rate limiting
– Invokes prompt pipeline → calls AI service client(s)
– Calls GitHub service client to fetch repo file tree / README if needed
– Persists metadata/logs to PostgreSQL
5) User clicks nodes → navigates to source files/dirs (client-side routing).
6) Analytics events sent in parallel to PostHog / Api-Analytics.

##### Architectural patterns & principles
- Layered architecture: UI ↔ API ↔ DB ↔ External services
- “Service” abstraction in backend for each external integration
- Drizzle ORM for type-safe DB interactions
- Server Actions in Next.js for light backend tasks (e.g., cache)
- Containerized deployment with Docker + Nginx
- CI/CD pipeline orchestrated in GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Frontend
    UI["User's Browser"]:::external
    UI -->|"Interacts with"| AppDir

    subgraph "Frontend (Next.js UI)"
        direction TB
        AppDir["src/app"]:::internal
        Page["page.tsx"]:::internal
        RepoPage["[username]/[repo]/page.tsx"]:::internal
        Layout["layout.tsx"]:::internal
        Providers["providers.tsx"]:::internal
        FetchBackend["src/lib/fetch-backend.ts"]:::internal
        subgraph "Server Actions"
            direction TB
            ActionsDir["src/app/_actions"]:::internal
            CacheAction["cache.ts"]:::internal
            GithubAction["github.ts"]:::internal
            RepoAction["repo.ts"]:::internal
        end
        subgraph "React Components"
            direction TB
            ComponentsDir["src/components"]:::internal
            MermaidComp["mermaid-diagram.tsx"]:::internal
            UIComponents["ui/"]:::internal
        end
        subgraph "Hooks"
            direction TB
            HooksDir["src/hooks"]:::internal
            UseDiagram["useDiagram.ts"]:::internal
            UseStar["useStarReminder.tsx"]:::internal
        end
        AppDir --> Page
        AppDir --> RepoPage
        AppDir --> Layout
        AppDir --> Providers
        AppDir --> FetchBackend
        AppDir --> ActionsDir
        ActionsDir --> CacheAction
        ActionsDir --> GithubAction
        ActionsDir --> RepoAction
        AppDir --> ComponentsDir
        ComponentsDir --> MermaidComp
        ComponentsDir --> UIComponents
        AppDir --> HooksDir
        HooksDir --> UseDiagram
        HooksDir --> UseStar
    end

    %% Hosting & CI/CD for Frontend
    subgraph "Hosting & CI/CD"
        direction TB
        Vercel["Vercel Hosting"]:::infra
        NextConfig["next.config.js"]:::infra
        DeployYml[".github/workflows/deploy.yml"]:::infra
    end
    UI --> Vercel
    DeployYml --> Vercel
    NextConfig --> Vercel

    %% Reverse Proxy
    subgraph "API Reverse Proxy"
        direction TB
        Nginx["Nginx"]:::infra
        NginxConf["api.conf"]:::infra
        NginxSetup["setup_nginx.sh"]:::infra
    end
    AppDir -->|HTTP REST| Nginx

    %% Backend Service
    subgraph "Backend (FastAPI)"
        direction TB
        Main["backend/app/main.py"]:::internal
        Routers["Routers"]:::internal
        subgraph "Generate & Modify Routers"
            direction TB
            GenerateRouter["generate.py"]:::internal
            ModifyRouter["modify.py"]:::internal
        end
        Limiter["core/limiter.py"]:::internal
        Prompts["prompts.py"]:::internal
        subgraph "Services"
            direction TB
            Claude["claude_service.py"]:::internal
            OpenAI1["o1_mini_openai_service.py"]:::internal
            OpenAI3["o3_mini_openai_service.py"]:::internal
            OpenRouter["o3_mini_openrouter_service.py"]:::internal
            OpenAI4["o4_mini_openai_service.py"]:::internal
            GitHubService["github_service.py"]:::internal
        end
        Nginx --> Main
        Main --> GenerateRouter
        Main --> ModifyRouter
        GenerateRouter --> Limiter
        ModifyRouter --> Limiter
        GenerateRouter --> Prompts
        ModifyRouter --> Prompts
        Prompts --> Claude
        Prompts --> OpenAI1
        Prompts --> OpenAI3
        Prompts --> OpenRouter
        Prompts --> OpenAI4
        Prompts --> GitHubService
        GenerateRouter -->|"SQL Query"| DB
        ModifyRouter -->|"SQL Query"| DB
        Main -->|Response Mermaid| Nginx
    end

    %% Database
    subgraph "Database (PostgreSQL)"
        direction TB
        DB["PostgreSQL"]:::data
        ORMConfig["drizzle.config.ts"]:::data
        Schema["src/server/db/schema.ts"]:::data
        DBIndex["src/server/db/index.ts"]:::data
    end
    DB --> ORMConfig
    DB --> Schema
    DB --> DBIndex

    %% DevOps Local
    subgraph "Local DevOps"
        direction TB
        DockerCompose["docker-compose.yml"]:::infra
        DBScript["start-database.sh"]:::infra
    end
    DockerCompose --> Nginx
    DockerCompose --> DB
    DockerCompose --> Main

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        GHAction[".github/workflows/deploy.yml"]:::infra
        DeployScript["backend/deploy.sh"]:::infra
        Entrypoint["backend/entrypoint.sh"]:::infra
    end
    GHAction --> DeployScript
    GHAction --> Entrypoint
    GHAction --> Vercel
    GHAction --> DockerCompose

    %% External Services
    subgraph "External Services"
        direction TB
        AIExt["OpenAI / Anthropic AI"]:::external
        GitHubAPI["GitHub REST API"]:::external
        Analytics["PostHog / Api-Analytics"]:::external
    end
    Claude --> AIExt
    OpenAI1 --> AIExt
    OpenAI3 --> AIExt
    OpenRouter --> AIExt
    OpenAI4 --> AIExt
    GitHubService --> GitHubAPI
    AppDir -->|Analytics events| Analytics
    Main -->|Analytics events| Analytics

    %% Click Events
    click AppDir "https://github.com/jabdy86/gitdiagram/tree/main/src/app"
    click Page "https://github.com/jabdy86/gitdiagram/blob/main/src/app/page.tsx"
    click RepoPage "https://github.com/jabdy86/gitdiagram/blob/main/src/app/[username]/[repo]/page.tsx"
    click Layout "https://github.com/jabdy86/gitdiagram/blob/main/src/app/layout.tsx"
    click Providers "https://github.com/jabdy86/gitdiagram/blob/main/src/app/providers.tsx"
    click ComponentsDir "https://github.com/jabdy86/gitdiagram/tree/main/src/components"
    click MermaidComp "https://github.com/jabdy86/gitdiagram/blob/main/src/components/mermaid-diagram.tsx"
    click HooksDir "https://github.com/jabdy86/gitdiagram/tree/main/src/hooks"
    click UseDiagram "https://github.com/jabdy86/gitdiagram/blob/main/src/hooks/useDiagram.ts"
    click UseStar "https://github.com/jabdy86/gitdiagram/blob/main/src/hooks/useStarReminder.tsx"
    click FetchBackend "https://github.com/jabdy86/gitdiagram/blob/main/src/lib/fetch-backend.ts"
    click ActionsDir "https://github.com/jabdy86/gitdiagram/tree/main/src/app/_actions"
    click CacheAction "https://github.com/jabdy86/gitdiagram/blob/main/src/app/_actions/cache.ts"
    click GithubAction "https://github.com/jabdy86/gitdiagram/blob/main/src/app/_actions/github.ts"
    click RepoAction "https://github.com/jabdy86/gitdiagram/blob/main/src/app/_actions/repo.ts"
    click DeployYml "https://github.com/jabdy86/gitdiagram/blob/main/.github/workflows/deploy.yml"
    click NextConfig "https://github.com/jabdy86/gitdiagram/blob/main/next.config.js"
    click Main "https://github.com/jabdy86/gitdiagram/blob/main/backend/app/main.py"
    click GenerateRouter "https://github.com/jabdy86/gitdiagram/blob/main/backend/app/routers/generate.py"
    click ModifyRouter "https://github.com/jabdy86/gitdiagram/blob/main/backend/app/routers/modify.py"
    click Limiter "https://github.com/jabdy86/gitdiagram/blob/main/backend/app/core/limiter.py"
    click Prompts "https://github.com/jabdy86/gitdiagram/blob/main/backend/app/prompts.py"
    click Claude "https://github.com/jabdy86/gitdiagram/blob/main/backend/app/services/claude_service.py"
    click OpenAI1 "https://github.com/jabdy86/gitdiagram/blob/main/backend/app/services/o1_mini_openai_service.py"
    click OpenAI3 "https://github.com/jabdy86/gitdiagram/blob/main/backend/app/services/o3_mini_openai_service.py"
    click OpenRouter "https://github.com/jabdy86/gitdiagram/blob/main/backend/app/services/o3_mini_openrouter_service.py"
    click OpenAI4 "https://github.com/jabdy86/gitdiagram/blob/main/backend/app/services/o4_mini_openai_service.py"
    click GitHubService "https://github.com/jabdy86/gitdiagram/blob/main/backend/app/services/github_service.py"
    click NginxConf "https://github.com/jabdy86/gitdiagram/blob/main/backend/nginx/api.conf"
    click NginxSetup "https://github.com/jabdy86/gitdiagram/blob/main/backend/nginx/setup_nginx.sh"
    click ORMConfig "https://github.com/jabdy86/gitdiagram/blob/main/drizzle.config.ts"
    click Schema "https://github.com/jabdy86/gitdiagram/blob/main/src/server/db/schema.ts"
    click DBIndex "https://github.com/jabdy86/gitdiagram/blob/main/src/server/db/index.ts"
    click DockerCompose "https://github.com/jabdy86/gitdiagram/blob/main/docker-compose.yml"
    click DBScript "https://github.com/jabdy86/gitdiagram/blob/main/start-database.sh"
    click GHAction "https://github.com/jabdy86/gitdiagram/blob/main/.github/workflows/deploy.yml"
    click DeployScript "https://github.com/jabdy86/gitdiagram/blob/main/backend/deploy.sh"
    click Entrypoint "https://github.com/jabdy86/gitdiagram/blob/main/backend/entrypoint.sh"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef data fill:#d4edda,stroke:#333,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef infra fill:#ffe5b4,stroke:#333,stroke-width:1px
```
