# mengtang1114-forks/gitdiagram architecture

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

- Interactive diagram: https://gitdiagram.com/mengtang1114-forks/gitdiagram
- Repository: https://github.com/mengtang1114-forks/gitdiagram
- Video tour (about a minute): https://gitdiagram.com/mengtang1114-forks/gitdiagram/video

## Overview

GitDiagram is a web product for generating interactive repository architecture diagrams and narrated explainer videos. The diagram workflow takes a repository request through GitHub ingestion, bounded source-context selection, AI explanation and graph generation, then serves an interactive diagram with linked code and export actions. A separate video workflow creates and stores a narrated film, offers playback and on-demand MP4 rendering. The graph emphasizes documented capabilities and sampled orchestration; links between unsampled internals are omitted where call ownership is uncertain.

Main entry points: [`src/app/api/generate/stream/route.ts`](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/api/generate/stream/route.ts) (Diagram endpoints), [`src/server/explainer/store.ts`](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/explainer/store.ts) (Video artifacts), [`src/app/[username]/[repo]/repo-page-client.tsx`](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/%5Busername%5D/%5Brepo%5D/repo-page-client.tsx) (Repository page), [`src/app/[username]/[repo]/video/video-watch-page-client.tsx`](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/%5Busername%5D/%5Brepo%5D/video/video-watch-page-client.tsx) (Video watch page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_diagram["Diagram workflow"]
  node_repo_page["Repository page"]
  node_diagram_api["Diagram endpoints<br/>[route.ts]"]
  node_repo_ingest["GitHub ingestion<br/>[github.ts]"]
  node_source_context["Source context"]
  node_ai_generation["AI generation<br/>[graph-planner.ts]"]
  node_diagram_graph["Graph compilation<br/>[graph.ts]"]
  node_diagram_state[("Diagram state<br/>[diagram-state.ts]")]
  node_diagram_ui["Interactive workspace"]
  node_diagram_export["Diagram export<br/>[export.ts]"]
end

subgraph group_video["Explainer videos"]
  node_video_page["Video watch page"]
  node_video_api["Video endpoints<br/>[route.ts]"]
  node_video_generation_api["Video generation<br/>[route.ts]"]
  node_video_pipeline["Narration and scenes<br/>[generate.ts]"]
  node_video_store[("Video artifacts<br/>[store.ts]")]
  node_video_player["Video player"]
  node_video_render_api["MP4 rendering<br/>[route.ts]"]
  node_video_render["Segment renderer<br/>[segments.ts]"]
  node_video_engine["Scene engine<br/>[stage.js]"]
end

subgraph group_browse["Discovery and browse"]
  node_browse_page["Browse catalog<br/>[page.tsx]"]
  node_browse_catalog["Catalog service<br/>[catalog.ts]"]
  node_browse_index[("Browse index")]
end

subgraph group_platform["Operations and sponsors"]
  node_admin_api["Admin operations<br/>[route.ts]"]
  node_admin_state["Operational state<br/>[state.ts]"]
  node_sponsor_route["Sponsor redirect<br/>[route.ts]"]
end

node_visitor(("Repository visitor"))
node_github["GitHub"]
node_ai_provider["AI provider"]
node_sponsor["Sponsor destination"]

node_visitor -->|"opens repository"| node_repo_page
node_repo_page -->|"requests diagram"| node_diagram_api
node_diagram_api -->|"fetches repository"| node_repo_ingest
node_repo_ingest -->|"reads tree and files"| node_github
node_diagram_api -->|"selects source"| node_source_context
node_diagram_api -->|"generates graph"| node_ai_generation
node_ai_generation -->|"streams completion"| node_ai_provider
node_diagram_api -->|"compiles graph"| node_diagram_graph
node_diagram_api -->|"persists state"| node_diagram_state
node_repo_page -->|"renders workspace"| node_diagram_ui
node_diagram_ui -->|"exports diagram"| node_diagram_export
node_visitor -->|"opens video"| node_video_page
node_video_page -->|"checks availability"| node_video_api
node_video_api -->|"reads artifact"| node_video_store
node_video_page -->|"plays video"| node_video_player
node_visitor -->|"requests generation"| node_video_generation_api
node_video_generation_api -->|"starts job"| node_video_pipeline
node_video_generation_api -->|"checks stored video"| node_video_store
node_video_pipeline -->|"stores artifact"| node_video_store
node_video_render_api -->|"reads artifact"| node_video_store
node_video_render_api -->|"renders segments"| node_video_render
node_video_render -->|"renders scenes"| node_video_engine
node_visitor -->|"browses"| node_browse_page
node_browse_page -->|"loads catalog"| node_browse_catalog
node_browse_catalog -->|"reads index"| node_browse_index
node_admin_api -->|"reads state"| node_admin_state
node_visitor -->|"follows sponsor link"| node_sponsor_route
node_sponsor_route -->|"redirects to"| node_sponsor

click node_repo_page "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/%5Busername%5D/%5Brepo%5D/repo-page-client.tsx"
click node_diagram_api "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/api/generate/stream/route.ts"
click node_repo_ingest "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/generate/github.ts"
click node_source_context "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/generate/repository-context.ts"
click node_ai_generation "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/generate/graph-planner.ts"
click node_diagram_graph "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/generate/graph.ts"
click node_diagram_state "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/storage/diagram-state.ts"
click node_diagram_ui "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/components/generation/repository-workspace.tsx"
click node_diagram_export "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/features/diagram/export.ts"
click node_video_page "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/%5Busername%5D/%5Brepo%5D/video/video-watch-page-client.tsx"
click node_video_api "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/api/video/route.ts"
click node_video_generation_api "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/api/video/generate/route.ts"
click node_video_pipeline "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/explainer/generate.ts"
click node_video_store "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/explainer/store.ts"
click node_video_player "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/components/explainer/explainer-video.tsx"
click node_video_render_api "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/api/video/render/route.ts"
click node_video_render "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/explainer/segments.ts"
click node_video_engine "https://github.com/mengtang1114-forks/gitdiagram/blob/main/public/video-engine/stage.js"
click node_browse_page "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/browse/page.tsx"
click node_browse_catalog "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/features/browse/catalog.ts"
click node_browse_index "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/browse-index-cache.ts"
click node_admin_api "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/api/admin/state/route.ts"
click node_admin_state "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/admin/state.ts"
click node_sponsor_route "https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/out/%5Bcampaign%5D/route.ts"

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_page,node_diagram_api,node_repo_ingest,node_source_context,node_ai_generation,node_diagram_graph,node_diagram_state,node_diagram_ui,node_diagram_export toneBlue
class node_video_page,node_video_api,node_video_generation_api,node_video_pipeline,node_video_store,node_video_player,node_video_render_api,node_video_render,node_video_engine toneAmber
class node_browse_page,node_browse_catalog,node_browse_index toneMint
class node_admin_api,node_admin_state,node_sponsor_route toneRose
class node_visitor,node_github,node_ai_provider,node_sponsor toneIndigo
```

## Components

### Diagram workflow

- [Repository page](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/%5Busername%5D/%5Brepo%5D/repo-page-client.tsx): `src/app/[username]/[repo]/repo-page-client.tsx`
- [Diagram endpoints](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/api/generate/stream/route.ts): `src/app/api/generate/stream/route.ts`
- [GitHub ingestion](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/generate/github.ts): `src/server/generate/github.ts`
- [Source context](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/generate/repository-context.ts): `src/server/generate/repository-context.ts`
- [AI generation](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/generate/graph-planner.ts): `src/server/generate/graph-planner.ts`
- [Graph compilation](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/generate/graph.ts): `src/server/generate/graph.ts`
- [Diagram state](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/storage/diagram-state.ts): `src/server/storage/diagram-state.ts`
- [Interactive workspace](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/components/generation/repository-workspace.tsx): `src/components/generation/repository-workspace.tsx`
- [Diagram export](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/features/diagram/export.ts): `src/features/diagram/export.ts`

### Explainer videos

- [Video watch page](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/%5Busername%5D/%5Brepo%5D/video/video-watch-page-client.tsx): `src/app/[username]/[repo]/video/video-watch-page-client.tsx`
- [Video endpoints](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/api/video/route.ts): `src/app/api/video/route.ts`
- [Video generation](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/api/video/generate/route.ts): `src/app/api/video/generate/route.ts`
- [Narration and scenes](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/explainer/generate.ts): `src/server/explainer/generate.ts`
- [Video artifacts](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/explainer/store.ts): `src/server/explainer/store.ts`
- [Video player](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/components/explainer/explainer-video.tsx): `src/components/explainer/explainer-video.tsx`
- [MP4 rendering](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/api/video/render/route.ts): `src/app/api/video/render/route.ts`
- [Segment renderer](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/explainer/segments.ts): `src/server/explainer/segments.ts`
- [Scene engine](https://github.com/mengtang1114-forks/gitdiagram/blob/main/public/video-engine/stage.js): `public/video-engine/stage.js`

### Discovery and browse

- [Browse catalog](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/browse/page.tsx): `src/app/browse/page.tsx`
- [Catalog service](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/features/browse/catalog.ts): `src/features/browse/catalog.ts`
- [Browse index](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/browse-index-cache.ts): `src/server/browse-index-cache.ts`

### Operations and sponsors

- [Admin operations](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/api/admin/state/route.ts): `src/app/api/admin/state/route.ts`
- [Operational state](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/server/admin/state.ts): `src/server/admin/state.ts`
- [Sponsor redirect](https://github.com/mengtang1114-forks/gitdiagram/blob/main/src/app/out/%5Bcampaign%5D/route.ts): `src/app/out/[campaign]/route.ts`

### Other components

- **Repository visitor**
- **GitHub**
- **AI provider**
- **Sponsor destination**

## Connections

- Repository visitor → Repository page: opens repository
- Repository page → Diagram endpoints: requests diagram
- Diagram endpoints → GitHub ingestion: fetches repository
- GitHub ingestion → GitHub: reads tree and files
- Diagram endpoints → Source context: selects source
- Diagram endpoints → AI generation: generates graph
- AI generation → AI provider: streams completion
- Diagram endpoints → Graph compilation: compiles graph
- Diagram endpoints → Diagram state: persists state
- Repository page → Interactive workspace: renders workspace
- Interactive workspace → Diagram export: exports diagram
- Repository visitor → Video watch page: opens video
- Video watch page → Video endpoints: checks availability
- Video endpoints → Video artifacts: reads artifact
- Video watch page → Video player: plays video
- Repository visitor → Video generation: requests generation
- Video generation → Narration and scenes: starts job
- Video generation → Video artifacts: checks stored video
- Narration and scenes → Video artifacts: stores artifact
- MP4 rendering → Video artifacts: reads artifact
- MP4 rendering → Segment renderer: renders segments
- Segment renderer → Scene engine: renders scenes
- Repository visitor → Browse catalog: browses
- Browse catalog → Catalog service: loads catalog
- Catalog service → Browse index: reads index
- Admin operations → Operational state: reads state
- Repository visitor → Sponsor redirect: follows sponsor link
- Sponsor redirect → Sponsor destination: redirects to