gaurav-chakraborty/gitdiagram

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.