GitDiagram

GitDiagram transforms GitHub repositories into interactive Mermaid.js architecture diagrams using a two-stage AI pipeline. It first generates a plain-English explanation of a repo’s architecture, then converts that explanation into a validated graph of systems, nodes, and edges — all cross-checked against the real file tree before rendering. The result is a clickable diagram where every component links directly to its source file or directory on GitHub.

The project runs a Next.js 16 frontend on Vercel and supports two generation backends: a FastAPI service deployed on Railway for production parity, or built-in Next.js Route Handlers for lightweight self-hosting. Cloudflare R2 stores diagram artifacts and Upstash Redis tracks complimentary daily quotas and terminal failure summaries. AI inference supports OpenAI, OpenRouter, and Atlas Cloud, switchable via environment configuration.

GitDiagram is fully open-source under the MIT license with a self-hosting path that requires only a Bun environment and an AI provider API key for the simplest configuration. The FastAPI backend adds Python 3.14 and uv for production-parity deployments with Docker Compose. Private repositories are supported via a GitHub personal access token stored client-side.

The project has grown to over 15,000 stars since its December 2024 launch, driven by its utility for developers onboarding to unfamiliar codebases. An active sponsor program and a rotating sponsor slot in the README fund ongoing development.

What You Get

• Two-stage AI generation pipeline - Produces a plain-English architecture explanation first, then converts it into a structured graph validated against the real file tree before compiling to Mermaid, eliminating hallucinated paths and invalid connections.
• Clickable diagram nodes - Every node tied to a real repository path becomes a link directly to the corresponding file or directory on GitHub, enabling seamless navigation from diagram to code.
• Dual backend architecture - Choose between a FastAPI service on Railway for production parity or built-in Next.js Route Handlers for zero-infrastructure self-hosting, switched via a single environment variable.
• Transparent cost estimation - Before generation begins, the app counts exact input tokens (falling back to character-based estimates) and displays the expected AI cost so users know what they’re spending.
• Private repository support - Provide a GitHub personal access token with repo scope to generate diagrams for private repos; tokens are stored client-side and never sent to the server unnecessarily.
• Export as Mermaid or PNG - Copy the raw Mermaid.js code for embedding in documentation or download the diagram as a PNG for presentations and reports.
• Complimentary daily quota gate - A Redis-backed token budget lets the hosted service offer free generations up to a daily limit, with clear messaging when the quota resets at 00:00 UTC.
• Multi-provider AI support - Switch between OpenAI, OpenRouter, and Atlas Cloud via environment configuration, with a validated list of supported models for each provider.

Common Use Cases

• Onboarding to a large open-source codebase - A new contributor pastes a GitHub URL into GitDiagram before their first PR, getting a clickable architecture overview that cuts exploration time from hours to minutes.
• Technical interview preparation - A candidate generates a diagram of a public project to understand and articulate its architecture during system design rounds, backed by a visual they can navigate live.
• Documentation for undocumented repositories - A team exports the generated Mermaid code to embed architecture diagrams in Confluence, Notion, or a wiki, bootstrapping documentation for legacy code with no existing diagrams.
• Open-source contribution planning - A developer uses the diagram to identify which subsystems are most interconnected or central, helping them choose high-impact areas to contribute to without reading every file.
• Code review orientation - A reviewer generating a diagram for an unfamiliar PR branch uses it to understand how the changed components relate to the rest of the system before diving into diffs.

Under The Hood

Architecture GitDiagram uses a clean dual-backend architecture where the Next.js frontend is fully decoupled from generation backends — either a Railway-hosted FastAPI service or in-repo Next.js Route Handlers, selected explicitly via environment variable with no fallback guessing. The generation pipeline follows a strict two-stage pattern: a first AI pass produces a plain-English architecture explanation from the filtered file tree and README, and a second pass converts that explanation into a structured graph of groups, nodes, and edges. The graph is validated against the actual file tree with up to three retry loops that feed structured validation feedback back into the model, then compiled to Mermaid only after passing. State flows one-directionally from generation to artifact storage in Cloudflare R2, with quota and failure metadata in Upstash Redis. This separation of explanation, graph planning, validation, and compilation into distinct stages makes each layer independently testable and replaceable.

Tech Stack The frontend runs Next.js 16 with React 19 Server Components and TypeScript in strict mode, styled with Tailwind CSS v4 and ShadCN/ui built on Radix UI primitives. Bun serves as the package manager, dev runtime, and the host for the Mermaid validation sidecar scripts used by the FastAPI backend. The backend is FastAPI with Python 3.14, Pydantic v2 for schema enforcement, and uv for dependency management, deployed via Uvicorn on Railway. Diagram artifacts are stored in Cloudflare R2 using the AWS S3 SDK; quota and failure state use Upstash Redis over HTTP. AI inference routes through OpenAI, OpenRouter, or Atlas Cloud — all sharing the same OpenAI SDK interface — with model pricing tables embedded in both the TypeScript and Python codebases for cost transparency.

Code Quality Both the frontend and backend have comprehensive test coverage: the TypeScript side uses Vitest with Testing Library, covering components, hooks, graph validation logic, Mermaid compilation, pricing calculations, and the complimentary gate; the Python backend uses pytest with httpx, testing every service layer from GitHub data fetching to graph validation and Mermaid compilation. Zod v4 validates parsed graph JSON on the TypeScript side; Pydantic v2 enforces the same schema on the Python side, keeping both in sync. Error handling is explicit throughout — typed exceptions in Python, typed throw paths in TypeScript, with terminal failure summaries stored in Redis so users see meaningful messages rather than generic errors. ESLint and Prettier enforce consistent style across the frontend, and the Python backend follows uv-managed project conventions.

What Makes It Unique The validation-retry loop is the core technical differentiator: instead of asking an AI to produce Mermaid syntax directly — which is notoriously brittle — GitDiagram generates a structured intermediate graph object, validates every node path against the real file tree and every edge against real node IDs, then feeds structured validation feedback back into the model for up to three attempts before failing gracefully. Mermaid syntax validation itself runs in a real Mermaid and DOMPurify environment (via linkedom) in both the Next.js server and a Bun sidecar for the FastAPI backend, catching rendering errors that regex approaches miss. Pre-generation cost estimation using exact token counts from the OpenAI token-counting API — with a character-based fallback — gives users rare transparency about what a generation will cost before they commit.

Self-Hosting

GitDiagram is released under the MIT License, which is a permissive open-source license with no copyleft restrictions. You can use it commercially, modify the source, redistribute it, and include it in proprietary systems without any obligation to open-source your own code. The only requirement is that the copyright notice and license text be preserved in copies or substantial portions of the software.

Running GitDiagram yourself requires a Bun environment and an AI provider API key at minimum. The simplest self-hosted configuration uses only the Next.js Route Handlers backend, which deploys as a standard Vercel project with environment variables for your OpenAI (or OpenRouter or Atlas Cloud) key. Adding the FastAPI backend for production parity requires Python 3.14 and uv — versions pinned to specific patch releases — plus a Bun installation for the Mermaid validation sidecar. Docker Compose is provided for local development parity. You are responsible for provisioning and maintaining your own Cloudflare R2 bucket (for diagram artifact storage), Upstash Redis instance (for quota and failure tracking), and the Railway deployment for the FastAPI backend if you choose the production-style path.

Compared to the hosted version at gitdiagram.com, a self-hosted deployment gives you full control over AI provider choice and model selection, no shared daily quota limits, and the ability to diagram private repositories without sending any data to a third-party hosted service. What you give up is the zero-configuration experience: you handle your own uptime, deploy updates manually, and manage API keys and infrastructure costs directly. There is no paid support tier or SLA for the open-source project; community support happens through GitHub Issues.