Key points
- The URL hack: Replace
hubwithdiagramin any GitHub URL —github.com/owner/repo→gitdiagram.com/owner/repo. No extensions, no cloning, no login. This follows the pattern popularized by Gitingest (hub→ingest): zero install, zero config, zero cognitive overhead. - The semantic leap in code visualization:
- *Generation 1 (file structure)*:
tree,git log --graph— shows what files exist, not how they collaborate. - *Generation 2 (dependencies)*:
madge,dependency-cruiser,pydeps— shows who imports whom, not what modules mean in business terms. - *Generation 3 (architecture semantics)*: GitDiagram — an LLM understands code meaning and produces diagrams labeled "Authentication" → "API Gateway" → "Data Layer" instead of
auth.js→api.js→db.js. - Pipeline design: 1. Repo fetched via GitHub API (default branch, recursive file tree, README); oversized truncated repos are rejected. 2. Source sampling of key runtime modules, preserving import relationships. 3. A single LLM call streams an architecture overview, then a structured graph AST (groups/nodes/edges/shapes/labels/paths). 4. Server-side validation: identifiers, connectivity, size limits, and — critically — that every link path actually exists in the repo. Invalid output retries with feedback. 5. A deterministic compiler converts the validated AST to Mermaid with full text escaping; links are restricted to github.com. 6. Browser-side rendering with sanitization and strict Mermaid security mode. 7. Results cached in R2 for instant repeat visits.
- Core architecture principle: the LLM only interprets semantics; it never outputs Mermaid directly. Structured AST + deterministic compilation makes errors far less likely than prompting an LLM for raw Mermaid — a mature pattern in LLM application engineering.
- Interactive, not static: every node links to the corresponding file or directory on GitHub. The diagram and the code are two views of the same thing, eliminating the usual "diagram drifts from code" problem.
- Private repo support: users enter a fine-grained, read-only GitHub PAT in the browser; the token is only sent in same-origin requests and never persisted server-side. Private diagrams are stored in a separate R2 namespace behind a server secret.
- Streaming generation: the LLM's architecture summary appears before the diagram, giving feedback during 30–60 second generations and letting users spot misinterpretations early (e.g., a test file mistaken for an entry point).
- Gitingest lineage: Gitingest turns repos into LLM-readable text; GitDiagram turns them into human-readable diagrams. Both share the insight that a GitHub repo is structured data an LLM can transform into any form — test cases, API docs, onboarding tutorials.
- Repository: https://github.com/ahmedkhaleel2004/gitdiagram
- Live: https://gitdiagram.com/
- License: MIT
- Stack: TypeScript (Next.js 16 + React 19)
- Traction: 145 stars (2026-09-18 GitHub Trending)
- Inspired by: Gitingest
Future directions
1. Dynamic diagrams that regenerate on every push, CI-style. 2. Drill-down levels — expand "Auth Service" into its internal architecture, then down to functions. 3. Data-flow annotations showing how user requests traverse layers. 4. Comparison views of two versions side by side for code review.
The bottleneck in code visualization was never drawing technology — it was the cost of understanding code. LLMs drop that cost from "an engineer reading for a week" to "one API call in 30 seconds." GitDiagram is the first product of that cost collapse, but unlikely the last.