# cemdrk/gitdiagram architecture

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

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

## Overview

GitDiagram accepts a GitHub repository, fetches its structure and README, uses Claude to produce an explanation and Mermaid diagram, then caches and displays the result. Users can request cost estimates, modify or regenerate diagrams, and provide an API key for large repositories. The graph covers the documented interactive source navigation and customization capabilities; some backend route internals were not excerpted, so those links are marked unverified.

Main entry points: [`src/hooks/useDiagram.ts`](https://github.com/cemdrk/gitdiagram/blob/main/src/hooks/useDiagram.ts) (Diagram workflow), [`backend/app/routers/generate.py`](https://github.com/cemdrk/gitdiagram/blob/main/backend/app/routers/generate.py) (Generate and cost routes), [`src/app/[username]/[repo]/page.tsx`](https://github.com/cemdrk/gitdiagram/blob/main/src/app/%5Busername%5D/%5Brepo%5D/page.tsx) (Repository page), [`backend/app/services/claude_service.py`](https://github.com/cemdrk/gitdiagram/blob/main/backend/app/services/claude_service.py) (Claude client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web experience"]
  node_repo_form["Repository form<br/>[main-card.tsx]"]
  node_repo_page["Repository page<br/>[page.tsx]"]
  node_diagram_hook["Diagram workflow<br/>[useDiagram.ts]"]
  node_backend_client["Backend client<br/>[fetch-backend.ts]"]
  node_diagram_view["Mermaid display"]
end

subgraph group_backend["Diagram generation"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_generate_api["Generate and cost routes<br/>[generate.py]"]
  node_modify_api["Modify route<br/>[modify.py]"]
  node_github_service["GitHub repository fetcher<br/>[github_service.py]"]
  node_claude_service["Claude client<br/>[claude_service.py]"]
  node_prompts["Diagram prompts<br/>[prompts.py]"]
end

subgraph group_data["Repository data"]
  node_cache_actions["Diagram cache actions<br/>[cache.ts]"]
  node_repo_actions["Repository metadata actions<br/>[repo.ts]"]
  node_cache_db[("Diagram cache<br/>[schema.ts]")]
end

subgraph group_integrations["External services"]
  node_github{{"GitHub"}}
  node_claude{{"Anthropic Claude"}}
  node_postgres[("PostgreSQL")]
end

node_visitor(("Repository visitor"))

node_visitor -->|"enters repository"| node_repo_form
node_repo_form -->|"navigates to"| node_repo_page
node_repo_page -->|"loads diagram"| node_diagram_hook
node_diagram_hook -->|"requests generation"| node_backend_client
node_diagram_hook -->|"checks and saves"| node_cache_actions
node_diagram_hook -->|"reads generation date"| node_repo_actions
node_diagram_hook -->|"provides diagram state"| node_repo_page
node_repo_page -->|"renders diagram"| node_diagram_view
node_backend_client -->|"sends API requests"| node_api_app
node_backend_client -->|"reads and caches"| node_cache_actions
node_cache_actions -->|"reads and writes"| node_cache_db
node_api_app -->|"registers routes"| node_generate_api
node_api_app -->|"registers routes"| node_modify_api
node_generate_api -->|"fetches repository data"| node_github_service
node_generate_api -->|"requests generation"| node_claude_service
node_generate_api -->|"uses prompts"| node_prompts
node_github_service -->|"fetches tree and README"| node_github
node_claude_service -->|"sends prompts"| node_claude
node_modify_api -.->|"requests diagram changes"| node_claude_service
node_modify_api -.->|"uses modification prompts"| node_prompts
node_generate_api -->|"estimates token cost"| node_claude_service

click node_repo_form "https://github.com/cemdrk/gitdiagram/blob/main/src/components/main-card.tsx"
click node_repo_page "https://github.com/cemdrk/gitdiagram/blob/main/src/app/%5Busername%5D/%5Brepo%5D/page.tsx"
click node_diagram_hook "https://github.com/cemdrk/gitdiagram/blob/main/src/hooks/useDiagram.ts"
click node_backend_client "https://github.com/cemdrk/gitdiagram/blob/main/src/lib/fetch-backend.ts"
click node_diagram_view "https://github.com/cemdrk/gitdiagram/blob/main/src/components/mermaid-diagram.tsx"
click node_cache_actions "https://github.com/cemdrk/gitdiagram/blob/main/src/app/_actions/cache.ts"
click node_repo_actions "https://github.com/cemdrk/gitdiagram/blob/main/src/app/_actions/repo.ts"
click node_cache_db "https://github.com/cemdrk/gitdiagram/blob/main/src/server/db/schema.ts"
click node_api_app "https://github.com/cemdrk/gitdiagram/blob/main/backend/app/main.py"
click node_generate_api "https://github.com/cemdrk/gitdiagram/blob/main/backend/app/routers/generate.py"
click node_modify_api "https://github.com/cemdrk/gitdiagram/blob/main/backend/app/routers/modify.py"
click node_github_service "https://github.com/cemdrk/gitdiagram/blob/main/backend/app/services/github_service.py"
click node_claude_service "https://github.com/cemdrk/gitdiagram/blob/main/backend/app/services/claude_service.py"
click node_prompts "https://github.com/cemdrk/gitdiagram/blob/main/backend/app/prompts.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_repo_form,node_repo_page,node_diagram_hook,node_backend_client,node_diagram_view toneBlue
class node_api_app,node_generate_api,node_modify_api,node_github_service,node_claude_service,node_prompts toneAmber
class node_cache_actions,node_repo_actions,node_cache_db toneMint
class node_github,node_claude,node_postgres toneRose
class node_visitor toneIndigo
```

## Components

### Web experience

- [Repository form](https://github.com/cemdrk/gitdiagram/blob/main/src/components/main-card.tsx): `src/components/main-card.tsx`
- [Repository page](https://github.com/cemdrk/gitdiagram/blob/main/src/app/%5Busername%5D/%5Brepo%5D/page.tsx): `src/app/[username]/[repo]/page.tsx`
- [Diagram workflow](https://github.com/cemdrk/gitdiagram/blob/main/src/hooks/useDiagram.ts): `src/hooks/useDiagram.ts`
- [Backend client](https://github.com/cemdrk/gitdiagram/blob/main/src/lib/fetch-backend.ts): `src/lib/fetch-backend.ts`
- [Mermaid display](https://github.com/cemdrk/gitdiagram/blob/main/src/components/mermaid-diagram.tsx): `src/components/mermaid-diagram.tsx`

### Diagram generation

- [FastAPI application](https://github.com/cemdrk/gitdiagram/blob/main/backend/app/main.py): `backend/app/main.py`
- [Generate and cost routes](https://github.com/cemdrk/gitdiagram/blob/main/backend/app/routers/generate.py): `backend/app/routers/generate.py`
- [Modify route](https://github.com/cemdrk/gitdiagram/blob/main/backend/app/routers/modify.py): `backend/app/routers/modify.py`
- [GitHub repository fetcher](https://github.com/cemdrk/gitdiagram/blob/main/backend/app/services/github_service.py): `backend/app/services/github_service.py`
- [Claude client](https://github.com/cemdrk/gitdiagram/blob/main/backend/app/services/claude_service.py): `backend/app/services/claude_service.py`
- [Diagram prompts](https://github.com/cemdrk/gitdiagram/blob/main/backend/app/prompts.py): `backend/app/prompts.py`

### Repository data

- [Diagram cache actions](https://github.com/cemdrk/gitdiagram/blob/main/src/app/_actions/cache.ts): `src/app/_actions/cache.ts`
- [Repository metadata actions](https://github.com/cemdrk/gitdiagram/blob/main/src/app/_actions/repo.ts): `src/app/_actions/repo.ts`
- [Diagram cache](https://github.com/cemdrk/gitdiagram/blob/main/src/server/db/schema.ts): `src/server/db/schema.ts`

### External services

- **GitHub**
- **Anthropic Claude**
- **PostgreSQL**

### Other components

- **Repository visitor**

## Connections

- Repository visitor → Repository form: enters repository (evidence: `src/components/main-card.tsx`)
- Repository form → Repository page: navigates to (evidence: `src/components/main-card.tsx`)
- Repository page → Diagram workflow: loads diagram (evidence: `src/app/[username]/[repo]/page.tsx`)
- Diagram workflow → Backend client: requests generation (evidence: `src/hooks/useDiagram.ts`)
- Diagram workflow → Diagram cache actions: checks and saves (evidence: `src/hooks/useDiagram.ts`)
- Diagram workflow → Repository metadata actions: reads generation date (evidence: `src/hooks/useDiagram.ts`)
- Diagram workflow → Repository page: provides diagram state (evidence: `src/app/[username]/[repo]/page.tsx`)
- Repository page → Mermaid display: renders diagram (evidence: `src/app/[username]/[repo]/page.tsx`)
- Backend client → FastAPI application: sends API requests (evidence: `src/lib/fetch-backend.ts`)
- Backend client → Diagram cache actions: reads and caches (evidence: `src/lib/fetch-backend.ts`)
- Diagram cache actions → Diagram cache: reads and writes (evidence: `src/app/_actions/cache.ts`)
- FastAPI application → Generate and cost routes: registers routes (evidence: `backend/app/main.py`)
- FastAPI application → Modify route: registers routes (evidence: `backend/app/main.py`)
- Generate and cost routes → GitHub repository fetcher: fetches repository data (evidence: `backend/app/routers/generate.py`)
- Generate and cost routes → Claude client: requests generation (evidence: `backend/app/routers/generate.py`)
- Generate and cost routes → Diagram prompts: uses prompts (evidence: `backend/app/routers/generate.py`)
- GitHub repository fetcher → GitHub: fetches tree and README (evidence: `backend/app/services/github_service.py`)
- Claude client → Anthropic Claude: sends prompts (evidence: `backend/app/services/claude_service.py`)
- Modify route → Claude client: requests diagram changes (evidence: `backend/app/routers/modify.py`)
- Modify route → Diagram prompts: uses modification prompts (evidence: `backend/app/routers/modify.py`)
- Generate and cost routes → Claude client: estimates token cost (evidence: `backend/app/routers/generate.py`)