# gaurav-chakraborty/gitdiagram architecture

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

- Interactive diagram: https://gitdiagram.com/gaurav-chakraborty/gitdiagram
- Repository: https://github.com/gaurav-chakraborty/gitdiagram

## Overview

1. **High-level shape**
   GitDiagram is a split-frontend / generation-backend system. The Next.js app owns the user experience, public pages, browse/catalog features, and browser-side interactions. A separate FastAPI service in `backend/` can run the long-lived diagram generation pipeline in production, while the Next app also has in-repo Route Handlers for a “next” generation mode.

2. **Primary user flow**
   The core flow is: user submits a GitHub repo URL → the system resolves repository metadata and reads the repo tree/README → an LLM turns that snapshot into an explanation and graph model → the graph is compiled into Mermaid → Mermaid is validated → the app renders an interactive diagram and stores the result for reuse. The final output is not just a picture; it includes explanation, graph structure, Mermaid source, and terminal generation status.

3. **Frontend application boundary**
   The Next.js app under `src/app` is the public product surface: landing page, repo pages, browse pages, sponsor page, and API routes. The repo-specific route `src/app/[username]/[repo]/page.tsx` is the canonical diagram page. Client-side behavior lives in reusable components and hooks under `src/components`, `src/hooks`, and `src/features`, with diagram state management abstracted away from rendering.

4. **Generation API boundary**
   There are two generation entry points:
   - `src/app/api/generate/*` for the Next-native path
   - `backend/app/routers/generate.py` for the FastAPI path  
   The frontend selects the backend explicitly through environment-driven configuration. This is important architecturally because the generation pipeline is shared conceptually, but deployed in two runtimes.

5. **Server-side generation pipeline**
   The generation subsystem in `src/server/generate` and `backend/app/services` is the heart of the product. It pulls repository data from GitHub, formats and cleans the input, estimates cost, selects model config, calls OpenAI/OpenRouter, and constructs a graph from the repo structure. The pipeline then validates graph paths and Mermaid syntax before returning a result the UI can safely render.

6. **Validation and safety gates**
   Diagram generation is guarded by multiple checks:
   - repo-path validation against the actual file tree
   - Mermaid validation before rendering
   - complimentary quota gating for free usage
   - terminal failure summaries when generation fails without a saved artifact  
   These checks prevent invalid diagrams from being surfaced and reduce repeated expensive model runs.

7. **State and persistence**
   Persistent state is intentionally split by concern:
   - **Cloudflare R2** stores successful diagram artifacts
   - **Upstash Redis** stores complimentary quota state and short-lived failure summaries
   - repository page and browse-related caching lives in `src/server/storage`
   - private repo persistence uses a separate namespace keyed off the user’s GitHub token  
   There is no database like Postgres in the runtime path; storage is object/kv based.

8. **GitHub integration**
   GitHub is the main source system. The app fetches repo metadata, default branch, recursive file tree, README, and stars. Private repository access is supported via a GitHub personal access token with `repo` scope, handled through the app UI and server auth utilities. The architecture treats GitHub as both the source of truth for code structure and the source of social metadata used in repo pages.

9. **Browse/index experience**
   The browse subsystem is separate from on-demand generation. `src/app/browse`, `src/features/browse`, and `src/app/api/browse-index` support a catalog of preexisting diagrams and hover previews. This is a read-optimized surface that reuses stored artifacts instead of regenerating diagrams on every request.

10. **Rendering, export, and social assets**
    The diagram UI is interactive and supports copy/export flows. Mermaid rendering is encapsulated in components like `mermaid-diagram.tsx`, with toolbar actions for copy/download. The app also generates Open Graph/Twitter images and repo-specific social cards under `src/app/[username]/[repo]` and `src/server/og`, which means diagram data feeds not only the main page but also social sharing assets.

11. **Backend implementation details**
    The `backend/` folder is a standalone FastAPI service with its own Python app structure (`routers`, `services`, `core`). It mirrors the same generation responsibilities as the Next backend: GitHub fetch, graph construction, Mermaid generation, quota/cost logic, and observability. A small Bun-based Mermaid validator bridge exists here so the Python service can validate diagrams with the same Mermaid/DOMPurify approach used by the Next runtime.

12. **Operational concerns**
    The system is deployed as a mixed stack: Vercel for the Next frontend, Railway for the long-lived FastAPI generator, Cloudflare R2 for artifacts, and Upstash Redis for lightweight state. CI is GitHub Actions, and the repo includes Docker and docker-compose support for local parity. Observability and error formatting are first-class in the codebase, which matters because generation is async, failure-prone, and externally dependent on GitHub and LLM providers.

Main entry points: [`src/app/api/generate/stream/route.ts`](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/api/generate/stream/route.ts) (Generate API), [`backend/app/services/graph_service.py`](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/backend/app/services/graph_service.py) (Backend services), [`src/server/generate/mermaid-validator.ts`](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/generate/mermaid-validator.ts) (Validation gates), [`src/server/generate/graph.ts`](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/generate/graph.ts) (Graph builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next app"]
  node_home["Landing<br/>page<br/>[page.tsx]"]
  node_repo_page["Repo page<br/>[page.tsx]"]
  node_browse_page["Browse<br/>catalog page<br/>[page.tsx]"]
  node_api_generate["Generate API<br/>route handlers<br/>[route.ts]"]
  node_api_preview["Preview API<br/>route handler<br/>[route.ts]"]
  node_browse_api["Browse index<br/>route handler<br/>[route.ts]"]
  node_repo_client["Repo client<br/>client UI"]
  node_diagram_ui["Diagram UI<br/>rendering components"]
  node_browse_ui["Browse UI<br/>catalog components<br/>[browse-catalog.tsx]"]
  node_diagram_hooks["Diagram hooks<br/>client hooks"]
  node_diagram_api["Diagram API client<br/>frontend adapter<br/>[api.ts]"]
  node_github_utils["GitHub URL tools<br/>parser<br/>[github-url.ts]"]
  node_cache_actions["Cache actions<br/>server actions<br/>[cache.ts]"]
end

subgraph group_generation["Generation pipeline"]
  node_github_fetch["GitHub fetch<br/>source integration<br/>[github.ts]"]
  node_graph_builder["Graph builder<br/>graph synthesis<br/>[graph.ts]"]
  node_mermaid_gen["Mermaid gen<br/>diagram synthesis<br/>[mermaid.ts]"]
  node_validation["Validation gates<br/>safety checks"]
  node_cost_gate["Quota & cost<br/>governance"]
  node_openai_client["LLM client<br/>model adapter<br/>[openai.ts]"]
end

subgraph group_storage["Persistence"]
  node_artifact_store[("Artifact store<br/>object storage<br/>[r2.ts]")]
  node_status_store[("Status store<br/>kv state<br/>[status-store.ts]")]
  node_quota_store[("Quota store<br/>kv state<br/>[quota-store.ts]")]
  node_browse_store[("Browse store<br/>catalog cache<br/>[browse-diagrams.ts]")]
end

subgraph group_backend["FastAPI backend"]
  node_backend_route["Generate router<br/>FastAPI route<br/>[generate.py]"]
  node_backend_services["Backend services<br/>pipeline services<br/>[graph_service.py]"]
  node_backend_validator["Mermaid bridge<br/>validator bridge"]
end

node_home -->|"open repo"| node_repo_page
node_repo_page -->|"hydrate"| node_repo_client
node_repo_client -->|"parse URL"| node_github_utils
node_repo_client -->|"request diagram"| node_diagram_api
node_repo_page -->|"render diagram"| node_diagram_ui
node_diagram_hooks -->|"stream updates"| node_diagram_api
node_browse_page -->|"browse catalog"| node_browse_ui
node_browse_ui -->|"load index"| node_browse_api
node_browse_ui -->|"reuse artifacts"| node_browse_store
node_api_generate -->|"fetch repo"| node_github_fetch
node_api_generate -->|"gate usage"| node_cost_gate
node_api_generate -->|"call model"| node_openai_client
node_api_generate -->|"build graph"| node_graph_builder
node_graph_builder -->|"compile"| node_mermaid_gen
node_mermaid_gen -->|"verify syntax"| node_validation
node_graph_builder -->|"verify paths"| node_validation
node_validation -->|"persist success"| node_artifact_store
node_validation -->|"record status"| node_status_store
node_cost_gate -->|"check quota"| node_quota_store
node_api_generate -->|"save output"| node_artifact_store
node_api_preview -->|"preview artifact"| node_artifact_store
node_cache_actions -->|"refresh cache"| node_browse_store
node_backend_route -->|"orchestrate"| node_backend_services
node_backend_services -->|"fetch repo"| node_github_fetch
node_backend_services -->|"call model"| node_openai_client
node_backend_services -->|"build graph"| node_graph_builder
node_backend_services -->|"validate mermaid"| node_backend_validator
node_backend_validator -.->|"share rules"| node_validation
node_diagram_ui -->|"display source"| node_mermaid_gen

click node_home "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/page.tsx"
click node_repo_page "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/[username]/[repo]/page.tsx"
click node_browse_page "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/browse/page.tsx"
click node_api_generate "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/api/generate/stream/route.ts"
click node_api_preview "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/api/diagram-preview/route.ts"
click node_browse_api "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/api/browse-index/route.ts"
click node_repo_client "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/[username]/[repo]/repo-page-client.tsx"
click node_diagram_ui "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/components/mermaid-diagram.tsx"
click node_browse_ui "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/components/browse-catalog.tsx"
click node_diagram_hooks "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/hooks/diagram/useDiagramStream.ts"
click node_diagram_api "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/features/diagram/api.ts"
click node_github_utils "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/features/diagram/github-url.ts"
click node_cache_actions "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/_actions/cache.ts"
click node_github_fetch "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/generate/github.ts"
click node_graph_builder "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/generate/graph.ts"
click node_mermaid_gen "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/generate/mermaid.ts"
click node_validation "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/generate/mermaid-validator.ts"
click node_cost_gate "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/generate/complimentary-gate.ts"
click node_openai_client "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/generate/openai.ts"
click node_artifact_store "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/storage/r2.ts"
click node_status_store "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/storage/status-store.ts"
click node_quota_store "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/storage/quota-store.ts"
click node_browse_store "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/storage/browse-diagrams.ts"
click node_backend_route "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/backend/app/routers/generate.py"
click node_backend_services "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/backend/app/services/graph_service.py"
click node_backend_validator "https://github.com/gaurav-chakraborty/gitdiagram/blob/main/backend/lib/mermaid-validator.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_home,node_repo_page,node_browse_page,node_api_generate,node_api_preview,node_browse_api,node_repo_client,node_diagram_ui,node_browse_ui,node_diagram_hooks,node_diagram_api,node_github_utils,node_cache_actions toneBlue
class node_github_fetch,node_graph_builder,node_mermaid_gen,node_validation,node_cost_gate,node_openai_client toneAmber
class node_artifact_store,node_status_store,node_quota_store,node_browse_store toneMint
class node_backend_route,node_backend_services,node_backend_validator toneRose
```

## Components

### Next app

Public product surface, client interactions, and in-repo generation entrypoints.

- [Landing](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/page.tsx): page · Marketing entry and repository submission surface. · `src/app/page.tsx`
- [Repo page](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/[username]/[repo]/page.tsx): page · Canonical repository diagram page with repo-specific route handling. · `src/app/[username]/[repo]/page.tsx`
- [Browse](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/browse/page.tsx): catalog page · Read-optimized catalog of preexisting diagrams. · `src/app/browse/page.tsx`
- [Generate API](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/api/generate/stream/route.ts): route handlers · Next-native generation and cost endpoints. · `src/app/api/generate/stream/route.ts`
- [Preview API](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/api/diagram-preview/route.ts): route handler · Diagram preview endpoint used by the UI. · `src/app/api/diagram-preview/route.ts`
- [Browse index](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/api/browse-index/route.ts): route handler · Serves catalog index data for browse views. · `src/app/api/browse-index/route.ts`
- [Repo client](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/[username]/[repo]/repo-page-client.tsx): client UI · Client-side repo page behavior, state, and interactions. · `src/app/[username]/[repo]/repo-page-client.tsx`
- [Diagram UI](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/components/mermaid-diagram.tsx): rendering components · Interactive Mermaid rendering, toolbar, export, and copy flows. · `src/components/mermaid-diagram.tsx`
- [Browse UI](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/components/browse-catalog.tsx): catalog components · Browse controls, hover previews, and catalog result rendering. · `src/components/browse-catalog.tsx`
- [Diagram hooks](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/hooks/diagram/useDiagramStream.ts): client hooks · Browser-side streaming, export, and diagram state orchestration. · `src/hooks/diagram/useDiagramStream.ts`
- [Diagram API client](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/features/diagram/api.ts): frontend adapter · Client adapter for diagram generation, SSE, and cost calls. · `src/features/diagram/api.ts`
- [GitHub URL tools](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/features/diagram/github-url.ts): parser · URL parsing and repo identity normalization for the user flow. · `src/features/diagram/github-url.ts`
- [Cache actions](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/app/_actions/cache.ts): server actions · Next server actions used to manage cached repo/page state. · `src/app/_actions/cache.ts`

### Generation pipeline

Shared repo-to-diagram workflow and validation logic.

- [GitHub fetch](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/generate/github.ts): source integration · Repository metadata, tree, README, and star retrieval. · `src/server/generate/github.ts`
- [Graph builder](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/generate/graph.ts): graph synthesis · Turns repository snapshots into structured graph output. · `src/server/generate/graph.ts`
- [Mermaid gen](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/generate/mermaid.ts): diagram synthesis · Compiles graph output into Mermaid source. · `src/server/generate/mermaid.ts`
- [Validation gates](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/generate/mermaid-validator.ts): safety checks · Repo-path and Mermaid validation before rendering or storage. · `src/server/generate/mermaid-validator.ts`
- [Quota & cost](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/generate/complimentary-gate.ts): governance · Complimentary usage gating and cost estimation. · `src/server/generate/complimentary-gate.ts`
- [LLM client](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/generate/openai.ts): model adapter · Model selection and provider access for generation. · `src/server/generate/openai.ts`

### Persistence

Artifact, cache, quota, and status storage.

- [Artifact store](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/storage/r2.ts): object storage · Persists successful diagram artifacts for reuse. · `src/server/storage/r2.ts`
- [Status store](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/storage/status-store.ts): kv state · Short-lived generation status and failure summaries. · `src/server/storage/status-store.ts`
- [Quota store](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/storage/quota-store.ts): kv state · Complimentary quota tracking and gating state. · `src/server/storage/quota-store.ts`
- [Browse store](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/src/server/storage/browse-diagrams.ts): catalog cache · Cached browse index and stored diagram catalog state. · `src/server/storage/browse-diagrams.ts`

### FastAPI backend

Standalone Python service for long-lived generation.

- [Generate router](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/backend/app/routers/generate.py): FastAPI route · Python generation entrypoint mirroring the Next-native path. · `backend/app/routers/generate.py`
- [Backend services](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/backend/app/services/graph_service.py): pipeline services · Python-side generation, validation, and provider orchestration. · `backend/app/services/graph_service.py`
- [Mermaid bridge](https://github.com/gaurav-chakraborty/gitdiagram/blob/main/backend/lib/mermaid-validator.ts): validator bridge · Bun-based Mermaid validation bridge for the Python service. · `backend/lib/mermaid-validator.ts`

## Connections

- Landing → Repo page: open repo · Users move from landing into a repository-specific diagram page.
- Repo page → Repo client: hydrate · The page hands off to client-side repo interactions and generation state.
- Repo client → GitHub URL tools: parse URL · Repository URLs are normalized before generation.
- Repo client → Diagram API client: request diagram · Client triggers generation, streaming, and cost operations.
- Repo page → Diagram UI: render diagram · Rendered results are shown through the Mermaid diagram surface.
- Diagram hooks → Diagram API client: stream updates · Hooks consume SSE and orchestrate diagram generation state.
- Browse → Browse UI: browse catalog · Browse page renders catalog controls and preview surfaces.
- Browse UI → Browse index: load index · Catalog data is fetched from the browse index route.
- Browse UI → Browse store: reuse artifacts · Browse experiences read from stored diagram catalog data.
- Generate API → GitHub fetch: fetch repo · Next-native generation starts by pulling repository data from GitHub.
- Generate API → Quota & cost: gate usage · Complimentary access and cost estimation are checked before generation.
- Generate API → LLM client: call model · The pipeline sends the cleaned snapshot to an LLM provider.
- Generate API → Graph builder: build graph · Structured repository data is converted into a graph model.
- Graph builder → Mermaid gen: compile · The graph model is transformed into Mermaid source.
- Mermaid gen → Validation gates: verify syntax · Generated Mermaid is validated before being surfaced to users.
- Graph builder → Validation gates: verify paths · Graph nodes and paths are checked against repository structure.
- Validation gates → Artifact store: persist success · Successful artifacts are stored for reuse.
- Validation gates → Status store: record status · Failures and terminal generation state are stored briefly.
- Quota & cost → Quota store: check quota · Complimentary usage state is read and updated in KV storage.
- Generate API → Artifact store: save output · Rendered diagram artifacts are written for later reuse.
- Preview API → Artifact store: preview artifact · Preview rendering reads from stored or generated artifacts.
- Cache actions → Browse store: refresh cache · Server actions update cached browse and page state.
- Generate router → Backend services: orchestrate · FastAPI router delegates to backend generation services.
- Backend services → GitHub fetch: fetch repo · Backend pipeline also pulls repository snapshots from GitHub.
- Backend services → LLM client: call model · Backend generation uses the same provider abstraction conceptually.
- Backend services → Graph builder: build graph · Python service mirrors graph construction responsibilities.
- Backend services → Mermaid bridge: validate mermaid · Backend uses the Bun bridge for Mermaid validation.
- Mermaid bridge → Validation gates: share rules · Validation behavior is aligned across runtimes.
- Diagram UI → Mermaid gen: display source · The UI renders Mermaid produced by the generation pipeline.