GitDiagram is a web tool that turns any public or private GitHub repository into an interactive architecture diagram. It is built for developers who have to understand code they did not write: reviewers landing on an unfamiliar pull request, engineers sizing up a dependency before adopting it, new hires in their first week, and anyone who has scrolled a file tree trying to work out which part talks to which. The project is MIT-licensed, written mostly in TypeScript, and has gathered more than 16,000 stars since it first appeared in December 2024.
What it does
Point it at a repository and it produces a system-level graph of that codebase. The README is explicit that this is meant to be architecture-first: it converts the repository tree, the README, and bounded source excerpts into a diagram of components and their relationships, rather than simply drawing the folder hierarchy back at you.
The features that matter in daily use:
- Interactive source links. Click a box in the diagram and it opens the real file or directory on GitHub. That is the part the video leans on hardest, and it is what separates this from a static picture — the diagram doubles as a navigation index.
- Streaming generation. The written explanation arrives while the graph is still being planned, so you are not staring at a spinner.
- Private repositories. You supply a GitHub token locally in the browser; private artifacts are kept in a separate protected storage namespace.
- Export. Copy the Mermaid source, or download the rendered diagram as a PNG — useful if you want the result in a design doc or a wiki page rather than in a browser tab.
- Provider choice. OpenAI by default, with OpenRouter available for self-hosted deployments.
There is also a URL trick that does a lot of the project's marketing for it: replace hub with diagram in any GitHub URL and the diagram for that repository opens.
How it works
The hosted app is a Next.js 16 App Router project on React 19, with Tailwind CSS and Radix UI for the interface. Generation is not a separate service: the endpoints are same-origin Next.js Route Handlers running on Vercel's Bun runtime. The README goes out of its way to say there is no separate FastAPI implementation, no Postgres database and no Neon runtime — worth knowing, because older write-ups about this project describe exactly that arrangement.
Around the generation path sit a few supporting pieces. Rendered diagram artifacts live in Cloudflare R2. Upstash Redis handles quota accounting, cancellation, locks, and short-lived failure state, which is what lets a long generation be aborted rather than left to burn tokens. The API exposes a cost-estimation route that runs before a generation, so the price of a job is known up front. PostHog covers analytics. Vercel is the only live runtime; an offline Railway and Docker recipe is kept around purely for disaster recovery.
Getting started
The fastest path needs nothing installed and no account: open gitdiagram.com and paste a repository URL, or edit an existing GitHub URL in place with the hub to diagram swap. For a private repository, provide a GitHub token, which stays in your browser.
Self-hosting is the other route, and the MIT license makes it straightforward. You will need your own OpenAI or OpenRouter key selected through the AI_PROVIDER setting, an R2 bucket for artifacts, and an Upstash Redis instance for coordination. Vercel is the supported target; the Docker recipe exists but is described as a fallback rather than the recommended deployment.
When to use it / when not
This is a first-pass orientation tool. It is at its best when you have thirty seconds and an unfamiliar repository, when you are onboarding someone, when you are deciding whether a library's structure is something you want to live with, or when you need a diagram of your own project for a document and do not want to draw one by hand.
It is not a replacement for reading the code. The diagram is a model's interpretation of the tree, the README and a bounded slice of source — bounded meaning very large codebases are necessarily summarised coarsely, and anything the model infers about a relationship can be wrong. Treat the output as a map that tells you where to look, not as a specification. The diagram is also a snapshot rather than something that tracks the repository as it changes. And if your code is private and sensitive, note that the hosted version sends material to a third-party model provider; that is the case for self-hosting with your own key.
GitDiagram is worth taking seriously if you regularly land in codebases that are not yours — consultants, reviewers, open-source contributors, and anyone writing onboarding material. The value is not the picture itself so much as the clickable path from "what is this system shaped like" to "which file do I open first," and it gets you there in under a minute with no setup at all. For teams with strict code-confidentiality rules, the self-hosted route is the version to evaluate.