# rogoveo/gitdiagram architecture

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

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

## Overview

GitDiagram accepts a repository page request and produces an interactive architecture diagram with a streamed explanation; users can inspect linked components and export the diagram. A separate video workflow serves existing explainers and, when enabled, generates and renders narrated videos. The graph emphasizes the evidenced diagram-generation calls and video API boundaries. Several feature and storage modules are represented from the repository tree and README, but their internal wiring is not shown in the sampled excerpts.

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

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_diagram_ui["Diagram experience"]
  node_repo_page["Repository page"]
  node_workspace["Diagram workspace"]
  node_diagram_hook["Diagram state hook<br/>[useDiagram.ts]"]
  node_export_ui["Diagram export<br/>[diagram-export.tsx]"]
end

subgraph group_diagram_runtime["Diagram generation"]
  node_diagram_api["Diagram API routes<br/>[route.ts]"]
  node_admission["Request admission"]
  node_github_ingest["GitHub ingestion<br/>[github.ts]"]
  node_source_context["Source context<br/>[source-context.ts]"]
  node_repository_context["Context selection"]
  node_model_stream["Model streaming<br/>[openai.ts]"]
  node_graph_planner["Graph validation<br/>[graph-planner.ts]"]
  node_graph_compile["Diagram compilation<br/>[graph.ts]"]
  node_diagram_state[("Diagram persistence<br/>[diagram-state.ts]")]
  node_diagram_preview["Diagram preview<br/>[route.ts]"]
end

subgraph group_video_runtime["Explainer videos"]
  node_video_page["Video watch page"]
  node_video_player["Explainer player"]
  node_video_api["Video catalog API<br/>[route.ts]"]
  node_video_generate_api["Video generation API<br/>[route.ts]"]
  node_video_generate["Video generation pipeline<br/>[generate.ts]"]
  node_video_store[("Video artifact store<br/>[store.ts]")]
  node_video_render_api["MP4 render API<br/>[route.ts]"]
  node_video_segments["Segmented renderer<br/>[segments.ts]"]
  node_video_engine["Scene engine<br/>[stage.js]"]
end

subgraph group_discovery["Browse and discovery"]
  node_browse["Browse catalog<br/>[browse-catalog.tsx]"]
  node_browse_api["Browse index API<br/>[route.ts]"]
  node_browse_index[("Browse index")]
end

subgraph group_operations["Operations and sponsorship"]
  node_admin["Admin dashboard"]
  node_sponsor["Sponsor redirect<br/>[route.ts]"]
end

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

node_visitor -->|"opens repository"| node_repo_page
node_repo_page -->|"loads state"| node_diagram_hook
node_repo_page -->|"renders workspace"| node_workspace
node_diagram_hook -->|"requests generation"| node_diagram_api
node_diagram_api -->|"admits request"| node_admission
node_diagram_api -->|"fetches repository"| node_github_ingest
node_github_ingest -->|"reads repository"| node_github
node_diagram_api -->|"fetches source"| node_source_context
node_source_context -->|"selects context"| node_repository_context
node_diagram_api -->|"streams explanation"| node_model_stream
node_model_stream -->|"requests completion"| node_ai_provider
node_diagram_api -->|"validates graph"| node_graph_planner
node_graph_planner -->|"requests graph"| node_ai_provider
node_diagram_api -->|"compiles diagram"| node_graph_compile
node_graph_compile -->|"persists state"| node_diagram_state
node_repo_page -.->|"loads preview"| node_diagram_preview
node_workspace -->|"offers export"| node_export_ui
node_visitor -->|"opens video"| node_video_page
node_video_page -->|"shows player"| node_video_player
node_video_player -->|"checks availability"| node_video_api
node_video_api -->|"reads artifact"| node_video_store
node_video_generate_api -->|"checks artifact"| node_video_store
node_video_generate_api -->|"starts job"| node_video_generate
node_video_generate -->|"stores video"| node_video_store
node_video_render_api -->|"reads artifact"| node_video_store
node_video_render_api -->|"renders MP4"| node_video_segments
node_video_segments -->|"renders scenes"| node_video_engine
node_visitor -->|"explores catalog"| node_browse
node_browse -->|"loads index"| node_browse_api
node_browse_api -->|"reads index"| node_browse_index
node_admin -.->|"manages service"| node_visitor
node_visitor -->|"follows campaign"| node_sponsor
node_sponsor -->|"redirects"| node_sponsor_site

click node_repo_page "https://github.com/rogoveo/gitdiagram/blob/main/src/app/%5Busername%5D/%5Brepo%5D/repo-page-client.tsx"
click node_workspace "https://github.com/rogoveo/gitdiagram/blob/main/src/components/generation/repository-workspace.tsx"
click node_diagram_hook "https://github.com/rogoveo/gitdiagram/blob/main/src/hooks/useDiagram.ts"
click node_diagram_api "https://github.com/rogoveo/gitdiagram/blob/main/src/app/api/generate/stream/route.ts"
click node_admission "https://github.com/rogoveo/gitdiagram/blob/main/src/server/generate/request-admission.ts"
click node_github_ingest "https://github.com/rogoveo/gitdiagram/blob/main/src/server/generate/github.ts"
click node_source_context "https://github.com/rogoveo/gitdiagram/blob/main/src/server/generate/source-context.ts"
click node_repository_context "https://github.com/rogoveo/gitdiagram/blob/main/src/server/generate/repository-context.ts"
click node_model_stream "https://github.com/rogoveo/gitdiagram/blob/main/src/server/generate/openai.ts"
click node_graph_planner "https://github.com/rogoveo/gitdiagram/blob/main/src/server/generate/graph-planner.ts"
click node_graph_compile "https://github.com/rogoveo/gitdiagram/blob/main/src/server/generate/graph.ts"
click node_diagram_state "https://github.com/rogoveo/gitdiagram/blob/main/src/server/storage/diagram-state.ts"
click node_diagram_preview "https://github.com/rogoveo/gitdiagram/blob/main/src/app/api/diagram-preview/route.ts"
click node_export_ui "https://github.com/rogoveo/gitdiagram/blob/main/src/components/generation/diagram-export.tsx"
click node_video_page "https://github.com/rogoveo/gitdiagram/blob/main/src/app/%5Busername%5D/%5Brepo%5D/video/video-watch-page-client.tsx"
click node_video_player "https://github.com/rogoveo/gitdiagram/blob/main/src/components/explainer/explainer-video.tsx"
click node_video_api "https://github.com/rogoveo/gitdiagram/blob/main/src/app/api/video/route.ts"
click node_video_generate_api "https://github.com/rogoveo/gitdiagram/blob/main/src/app/api/video/generate/route.ts"
click node_video_generate "https://github.com/rogoveo/gitdiagram/blob/main/src/server/explainer/generate.ts"
click node_video_store "https://github.com/rogoveo/gitdiagram/blob/main/src/server/explainer/store.ts"
click node_video_render_api "https://github.com/rogoveo/gitdiagram/blob/main/src/app/api/video/render/route.ts"
click node_video_segments "https://github.com/rogoveo/gitdiagram/blob/main/src/server/explainer/segments.ts"
click node_video_engine "https://github.com/rogoveo/gitdiagram/blob/main/public/video-engine/stage.js"
click node_browse "https://github.com/rogoveo/gitdiagram/blob/main/src/components/browse-catalog.tsx"
click node_browse_api "https://github.com/rogoveo/gitdiagram/blob/main/src/app/api/browse-index/route.ts"
click node_browse_index "https://github.com/rogoveo/gitdiagram/blob/main/src/server/browse-index-cache.ts"
click node_admin "https://github.com/rogoveo/gitdiagram/blob/main/src/app/admin/admin-dashboard.tsx"
click node_sponsor "https://github.com/rogoveo/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_workspace,node_diagram_hook,node_export_ui toneBlue
class node_diagram_api,node_admission,node_github_ingest,node_source_context,node_repository_context,node_model_stream,node_graph_planner,node_graph_compile,node_diagram_state,node_diagram_preview toneAmber
class node_video_page,node_video_player,node_video_api,node_video_generate_api,node_video_generate,node_video_store,node_video_render_api,node_video_segments,node_video_engine toneMint
class node_browse,node_browse_api,node_browse_index toneRose
class node_admin,node_sponsor,node_visitor,node_github,node_ai_provider,node_sponsor_site toneIndigo
```

## Components

### Diagram experience

- [Repository page](https://github.com/rogoveo/gitdiagram/blob/main/src/app/%5Busername%5D/%5Brepo%5D/repo-page-client.tsx): `src/app/[username]/[repo]/repo-page-client.tsx`
- [Diagram workspace](https://github.com/rogoveo/gitdiagram/blob/main/src/components/generation/repository-workspace.tsx): `src/components/generation/repository-workspace.tsx`
- [Diagram state hook](https://github.com/rogoveo/gitdiagram/blob/main/src/hooks/useDiagram.ts): `src/hooks/useDiagram.ts`
- [Diagram export](https://github.com/rogoveo/gitdiagram/blob/main/src/components/generation/diagram-export.tsx): `src/components/generation/diagram-export.tsx`

### Diagram generation

- [Diagram API routes](https://github.com/rogoveo/gitdiagram/blob/main/src/app/api/generate/stream/route.ts): `src/app/api/generate/stream/route.ts`
- [Request admission](https://github.com/rogoveo/gitdiagram/blob/main/src/server/generate/request-admission.ts): `src/server/generate/request-admission.ts`
- [GitHub ingestion](https://github.com/rogoveo/gitdiagram/blob/main/src/server/generate/github.ts): `src/server/generate/github.ts`
- [Source context](https://github.com/rogoveo/gitdiagram/blob/main/src/server/generate/source-context.ts): `src/server/generate/source-context.ts`
- [Context selection](https://github.com/rogoveo/gitdiagram/blob/main/src/server/generate/repository-context.ts): `src/server/generate/repository-context.ts`
- [Model streaming](https://github.com/rogoveo/gitdiagram/blob/main/src/server/generate/openai.ts): `src/server/generate/openai.ts`
- [Graph validation](https://github.com/rogoveo/gitdiagram/blob/main/src/server/generate/graph-planner.ts): `src/server/generate/graph-planner.ts`
- [Diagram compilation](https://github.com/rogoveo/gitdiagram/blob/main/src/server/generate/graph.ts): `src/server/generate/graph.ts`
- [Diagram persistence](https://github.com/rogoveo/gitdiagram/blob/main/src/server/storage/diagram-state.ts): `src/server/storage/diagram-state.ts`
- [Diagram preview](https://github.com/rogoveo/gitdiagram/blob/main/src/app/api/diagram-preview/route.ts): `src/app/api/diagram-preview/route.ts`

### Explainer videos

- [Video watch page](https://github.com/rogoveo/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`
- [Explainer player](https://github.com/rogoveo/gitdiagram/blob/main/src/components/explainer/explainer-video.tsx): `src/components/explainer/explainer-video.tsx`
- [Video catalog API](https://github.com/rogoveo/gitdiagram/blob/main/src/app/api/video/route.ts): `src/app/api/video/route.ts`
- [Video generation API](https://github.com/rogoveo/gitdiagram/blob/main/src/app/api/video/generate/route.ts): `src/app/api/video/generate/route.ts`
- [Video generation pipeline](https://github.com/rogoveo/gitdiagram/blob/main/src/server/explainer/generate.ts): `src/server/explainer/generate.ts`
- [Video artifact store](https://github.com/rogoveo/gitdiagram/blob/main/src/server/explainer/store.ts): `src/server/explainer/store.ts`
- [MP4 render API](https://github.com/rogoveo/gitdiagram/blob/main/src/app/api/video/render/route.ts): `src/app/api/video/render/route.ts`
- [Segmented renderer](https://github.com/rogoveo/gitdiagram/blob/main/src/server/explainer/segments.ts): `src/server/explainer/segments.ts`
- [Scene engine](https://github.com/rogoveo/gitdiagram/blob/main/public/video-engine/stage.js): `public/video-engine/stage.js`

### Browse and discovery

- [Browse catalog](https://github.com/rogoveo/gitdiagram/blob/main/src/components/browse-catalog.tsx): `src/components/browse-catalog.tsx`
- [Browse index API](https://github.com/rogoveo/gitdiagram/blob/main/src/app/api/browse-index/route.ts): `src/app/api/browse-index/route.ts`
- [Browse index](https://github.com/rogoveo/gitdiagram/blob/main/src/server/browse-index-cache.ts): `src/server/browse-index-cache.ts`

### Operations and sponsorship

- [Admin dashboard](https://github.com/rogoveo/gitdiagram/blob/main/src/app/admin/admin-dashboard.tsx): `src/app/admin/admin-dashboard.tsx`
- [Sponsor redirect](https://github.com/rogoveo/gitdiagram/blob/main/src/app/out/%5Bcampaign%5D/route.ts): `src/app/out/[campaign]/route.ts`

### Other components

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

## Connections

- Repository visitor → Repository page: opens repository
- Repository page → Diagram state hook: loads state
- Repository page → Diagram workspace: renders workspace
- Diagram state hook → Diagram API routes: requests generation
- Diagram API routes → Request admission: admits request
- Diagram API routes → GitHub ingestion: fetches repository
- GitHub ingestion → GitHub: reads repository
- Diagram API routes → Source context: fetches source
- Source context → Context selection: selects context
- Diagram API routes → Model streaming: streams explanation
- Model streaming → AI model provider: requests completion
- Diagram API routes → Graph validation: validates graph
- Graph validation → AI model provider: requests graph
- Diagram API routes → Diagram compilation: compiles diagram
- Diagram compilation → Diagram persistence: persists state
- Repository page → Diagram preview: loads preview
- Diagram workspace → Diagram export: offers export
- Repository visitor → Video watch page: opens video
- Video watch page → Explainer player: shows player
- Explainer player → Video catalog API: checks availability
- Video catalog API → Video artifact store: reads artifact
- Video generation API → Video artifact store: checks artifact
- Video generation API → Video generation pipeline: starts job
- Video generation pipeline → Video artifact store: stores video
- MP4 render API → Video artifact store: reads artifact
- MP4 render API → Segmented renderer: renders MP4
- Segmented renderer → Scene engine: renders scenes
- Repository visitor → Browse catalog: explores catalog
- Browse catalog → Browse index API: loads index
- Browse index API → Browse index: reads index
- Admin dashboard → Repository visitor: manages service
- Repository visitor → Sponsor redirect: follows campaign
- Sponsor redirect → Sponsor destination: redirects