# ak4off/gitdiagram architecture

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

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

## Overview

GitDiagram turns a GitHub repository into an interactive architecture diagram and, optionally, a narrated explainer video. The main diagram workflow admits a generation request, retrieves repository metadata and selected source context, streams model-generated architecture and explanation, then compiles a diagram for the repository page. A separate cost endpoint estimates generation from the same bounded repository context. Video generation and MP4 rendering are distinct workflows, alongside browsing existing diagrams and videos. The tree and excerpts establish key route calls; links among unsampled subsystems are omitted where ownership is uncertain.

Main entry points: [`src/app/api/generate/stream/route.ts`](https://github.com/ak4off/gitdiagram/blob/main/src/app/api/generate/stream/route.ts) (Generation stream), [`src/app/api/video/generate/route.ts`](https://github.com/ak4off/gitdiagram/blob/main/src/app/api/video/generate/route.ts) (Video generation API), [`src/app/api/generate/cost/route.ts`](https://github.com/ak4off/gitdiagram/blob/main/src/app/api/generate/cost/route.ts) (Cost estimate API), [`src/app/api/video/render/route.ts`](https://github.com/ak4off/gitdiagram/blob/main/src/app/api/video/render/route.ts) (MP4 render API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_diagram["Diagram generation"]
  node_diagram_page["Repository page"]
  node_workspace["Diagram workspace"]
  node_generate_route["Generation stream<br/>[route.ts]"]
  node_admission["Request admission"]
  node_github_ingest["Repository ingestion<br/>[github.ts]"]
  node_source_context["Source selection<br/>[source-context.ts]"]
  node_repo_context["Context preparation"]
  node_model_stream["Explanation stream<br/>[openai.ts]"]
  node_graph_planner["Graph planning<br/>[graph-planner.ts]"]
  node_diagram_compile["Diagram compilation<br/>[graph.ts]"]
  node_cost_route["Cost estimate API<br/>[route.ts]"]
end

subgraph group_video["Video experience"]
  node_video_page["Video watch page"]
  node_video_player["Explainer player"]
  node_video_api["Video availability API<br/>[route.ts]"]
  node_video_generate["Video generation API<br/>[route.ts]"]
  node_video_pipeline["Video generation<br/>[generate.ts]"]
  node_video_planner["Planner selection<br/>[planner.ts]"]
  node_video_store[("Video artifacts<br/>[store.ts]")]
  node_render_api["MP4 render API<br/>[route.ts]"]
  node_segments["Segment renderer<br/>[segments.ts]"]
end

subgraph group_discovery["Browse and share"]
  node_browse_page["Browse catalog<br/>[page.tsx]"]
  node_browse_catalog["Catalog feature<br/>[catalog.ts]"]
  node_sponsor_redirect["Sponsor redirect<br/>[route.ts]"]
end

subgraph group_operations["Operations"]
  node_admin_page["Admin dashboard<br/>[page.tsx]"]
  node_admin_state["Admin state API<br/>[route.ts]"]
end

node_visitor(("Repository visitor"))
node_github{{"GitHub"}}
node_ai{{"AI providers"}}
node_objectstore[("Artifact storage")]

node_visitor -->|"opens repository"| node_diagram_page
node_diagram_page -->|"renders workspace"| node_workspace
node_visitor -->|"requests diagram"| node_generate_route
node_generate_route -->|"admits request"| node_admission
node_generate_route -->|"loads repository"| node_github_ingest
node_github_ingest -->|"fetches metadata"| node_github
node_generate_route -->|"fetches source"| node_source_context
node_source_context -->|"reads source"| node_github
node_generate_route -->|"streams completion"| node_model_stream
node_model_stream -->|"requests completion"| node_ai
node_generate_route -->|"validates graph"| node_graph_planner
node_graph_planner -->|"plans graph"| node_ai
node_generate_route -->|"compiles diagram"| node_diagram_compile
node_visitor -->|"requests estimate"| node_cost_route
node_cost_route -->|"loads repository"| node_github_ingest
node_cost_route -->|"prepares context"| node_repo_context
node_visitor -->|"opens video"| node_video_page
node_video_page -->|"shows player"| node_video_player
node_visitor -->|"checks availability"| node_video_api
node_video_api -->|"reads artifact"| node_video_store
node_visitor -->|"requests video"| node_video_generate
node_video_generate -->|"starts generation"| node_video_pipeline
node_video_generate -->|"chooses planner"| node_video_planner
node_video_generate -->|"checks artifact"| node_video_store
node_visitor -->|"requests MP4"| node_render_api
node_render_api -->|"reads artifact"| node_video_store
node_render_api -->|"renders segments"| node_segments
node_visitor -->|"browses repositories"| node_browse_page
node_visitor -->|"follows sponsor link"| node_sponsor_redirect
node_visitor -->|"opens admin"| node_admin_page
node_admin_page -->|"loads state"| node_admin_state

click node_diagram_page "https://github.com/ak4off/gitdiagram/blob/main/src/app/%5Busername%5D/%5Brepo%5D/repo-page-client.tsx"
click node_workspace "https://github.com/ak4off/gitdiagram/blob/main/src/components/generation/repository-workspace.tsx"
click node_generate_route "https://github.com/ak4off/gitdiagram/blob/main/src/app/api/generate/stream/route.ts"
click node_admission "https://github.com/ak4off/gitdiagram/blob/main/src/server/generate/request-admission.ts"
click node_github_ingest "https://github.com/ak4off/gitdiagram/blob/main/src/server/generate/github.ts"
click node_source_context "https://github.com/ak4off/gitdiagram/blob/main/src/server/generate/source-context.ts"
click node_repo_context "https://github.com/ak4off/gitdiagram/blob/main/src/server/generate/repository-context.ts"
click node_model_stream "https://github.com/ak4off/gitdiagram/blob/main/src/server/generate/openai.ts"
click node_graph_planner "https://github.com/ak4off/gitdiagram/blob/main/src/server/generate/graph-planner.ts"
click node_diagram_compile "https://github.com/ak4off/gitdiagram/blob/main/src/server/generate/graph.ts"
click node_cost_route "https://github.com/ak4off/gitdiagram/blob/main/src/app/api/generate/cost/route.ts"
click node_video_page "https://github.com/ak4off/gitdiagram/blob/main/src/app/%5Busername%5D/%5Brepo%5D/video/video-watch-page-client.tsx"
click node_video_player "https://github.com/ak4off/gitdiagram/blob/main/src/components/explainer/explainer-video.tsx"
click node_video_api "https://github.com/ak4off/gitdiagram/blob/main/src/app/api/video/route.ts"
click node_video_generate "https://github.com/ak4off/gitdiagram/blob/main/src/app/api/video/generate/route.ts"
click node_video_pipeline "https://github.com/ak4off/gitdiagram/blob/main/src/server/explainer/generate.ts"
click node_video_planner "https://github.com/ak4off/gitdiagram/blob/main/src/server/explainer/planner.ts"
click node_video_store "https://github.com/ak4off/gitdiagram/blob/main/src/server/explainer/store.ts"
click node_render_api "https://github.com/ak4off/gitdiagram/blob/main/src/app/api/video/render/route.ts"
click node_segments "https://github.com/ak4off/gitdiagram/blob/main/src/server/explainer/segments.ts"
click node_browse_page "https://github.com/ak4off/gitdiagram/blob/main/src/app/browse/page.tsx"
click node_browse_catalog "https://github.com/ak4off/gitdiagram/blob/main/src/features/browse/catalog.ts"
click node_sponsor_redirect "https://github.com/ak4off/gitdiagram/blob/main/src/app/out/%5Bcampaign%5D/route.ts"
click node_admin_page "https://github.com/ak4off/gitdiagram/blob/main/src/app/admin/page.tsx"
click node_admin_state "https://github.com/ak4off/gitdiagram/blob/main/src/app/api/admin/state/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_diagram_page,node_workspace,node_generate_route,node_admission,node_github_ingest,node_source_context,node_repo_context,node_model_stream,node_graph_planner,node_diagram_compile,node_cost_route toneBlue
class node_video_page,node_video_player,node_video_api,node_video_generate,node_video_pipeline,node_video_planner,node_video_store,node_render_api,node_segments,node_objectstore toneAmber
class node_browse_page,node_browse_catalog,node_sponsor_redirect toneMint
class node_admin_page,node_admin_state toneRose
class node_visitor,node_github,node_ai toneIndigo
```

## Components

### Diagram generation

- [Repository page](https://github.com/ak4off/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/ak4off/gitdiagram/blob/main/src/components/generation/repository-workspace.tsx): `src/components/generation/repository-workspace.tsx`
- [Generation stream](https://github.com/ak4off/gitdiagram/blob/main/src/app/api/generate/stream/route.ts): `src/app/api/generate/stream/route.ts`
- [Request admission](https://github.com/ak4off/gitdiagram/blob/main/src/server/generate/request-admission.ts): `src/server/generate/request-admission.ts`
- [Repository ingestion](https://github.com/ak4off/gitdiagram/blob/main/src/server/generate/github.ts): `src/server/generate/github.ts`
- [Source selection](https://github.com/ak4off/gitdiagram/blob/main/src/server/generate/source-context.ts): `src/server/generate/source-context.ts`
- [Context preparation](https://github.com/ak4off/gitdiagram/blob/main/src/server/generate/repository-context.ts): `src/server/generate/repository-context.ts`
- [Explanation stream](https://github.com/ak4off/gitdiagram/blob/main/src/server/generate/openai.ts): `src/server/generate/openai.ts`
- [Graph planning](https://github.com/ak4off/gitdiagram/blob/main/src/server/generate/graph-planner.ts): `src/server/generate/graph-planner.ts`
- [Diagram compilation](https://github.com/ak4off/gitdiagram/blob/main/src/server/generate/graph.ts): `src/server/generate/graph.ts`
- [Cost estimate API](https://github.com/ak4off/gitdiagram/blob/main/src/app/api/generate/cost/route.ts): `src/app/api/generate/cost/route.ts`

### Video experience

- [Video watch page](https://github.com/ak4off/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/ak4off/gitdiagram/blob/main/src/components/explainer/explainer-video.tsx): `src/components/explainer/explainer-video.tsx`
- [Video availability API](https://github.com/ak4off/gitdiagram/blob/main/src/app/api/video/route.ts): `src/app/api/video/route.ts`
- [Video generation API](https://github.com/ak4off/gitdiagram/blob/main/src/app/api/video/generate/route.ts): `src/app/api/video/generate/route.ts`
- [Video generation](https://github.com/ak4off/gitdiagram/blob/main/src/server/explainer/generate.ts): `src/server/explainer/generate.ts`
- [Planner selection](https://github.com/ak4off/gitdiagram/blob/main/src/server/explainer/planner.ts): `src/server/explainer/planner.ts`
- [Video artifacts](https://github.com/ak4off/gitdiagram/blob/main/src/server/explainer/store.ts): `src/server/explainer/store.ts`
- [MP4 render API](https://github.com/ak4off/gitdiagram/blob/main/src/app/api/video/render/route.ts): `src/app/api/video/render/route.ts`
- [Segment renderer](https://github.com/ak4off/gitdiagram/blob/main/src/server/explainer/segments.ts): `src/server/explainer/segments.ts`

### Browse and share

- [Browse catalog](https://github.com/ak4off/gitdiagram/blob/main/src/app/browse/page.tsx): `src/app/browse/page.tsx`
- [Catalog feature](https://github.com/ak4off/gitdiagram/blob/main/src/features/browse/catalog.ts): `src/features/browse/catalog.ts`
- [Sponsor redirect](https://github.com/ak4off/gitdiagram/blob/main/src/app/out/%5Bcampaign%5D/route.ts): `src/app/out/[campaign]/route.ts`

### Operations

- [Admin dashboard](https://github.com/ak4off/gitdiagram/blob/main/src/app/admin/page.tsx): `src/app/admin/page.tsx`
- [Admin state API](https://github.com/ak4off/gitdiagram/blob/main/src/app/api/admin/state/route.ts): `src/app/api/admin/state/route.ts`

### Other components

- **Repository visitor**
- **GitHub**
- **AI providers**
- **Artifact storage**

## Connections

- Repository visitor → Repository page: opens repository
- Repository page → Diagram workspace: renders workspace
- Repository visitor → Generation stream: requests diagram
- Generation stream → Request admission: admits request
- Generation stream → Repository ingestion: loads repository
- Repository ingestion → GitHub: fetches metadata
- Generation stream → Source selection: fetches source
- Source selection → GitHub: reads source
- Generation stream → Explanation stream: streams completion
- Explanation stream → AI providers: requests completion
- Generation stream → Graph planning: validates graph
- Graph planning → AI providers: plans graph
- Generation stream → Diagram compilation: compiles diagram
- Repository visitor → Cost estimate API: requests estimate
- Cost estimate API → Repository ingestion: loads repository
- Cost estimate API → Context preparation: prepares context
- Repository visitor → Video watch page: opens video
- Video watch page → Explainer player: shows player
- Repository visitor → Video availability API: checks availability
- Video availability API → Video artifacts: reads artifact
- Repository visitor → Video generation API: requests video
- Video generation API → Video generation: starts generation
- Video generation API → Planner selection: chooses planner
- Video generation API → Video artifacts: checks artifact
- Repository visitor → MP4 render API: requests MP4
- MP4 render API → Video artifacts: reads artifact
- MP4 render API → Segment renderer: renders segments
- Repository visitor → Browse catalog: browses repositories
- Repository visitor → Sponsor redirect: follows sponsor link
- Repository visitor → Admin dashboard: opens admin
- Admin dashboard → Admin state API: loads state