GitDiagram: architecture diagrams from a GitHub URL

What GitDiagram produces, and for whom

The README opens with a single promise: turn any public or private GitHub repository into an interactive architecture diagram in seconds. The word doing the work there is architecture. The project is explicit that it "converts a repository tree and README into a system-level graph instead of merely drawing folders", so the output is not a directory listing rendered as boxes. It is a graph of components, groups and edges, each linked to a real file or directory in the repository.

The audience follows from that. Someone joining a project and trying to work out where the request path lives will get more from this than from a file tree, because the diagram names components rather than paths. The same applies to a reviewer who wants a second opinion on how a codebase is structured before reading it. It is a poorer fit for anyone who wants to see branches, commits or merge history: nothing in the README or the repository files describes commit or branch visualisation, and the related searches that ask for a GitHub commit visualiser or a branch visualiser are asking for something this tool does not do.

There is also a shortcut worth knowing. The README states that you can replace `hub` with `diagram` in a GitHub URL to open its diagram, so a repository at github.com/owner/repo becomes reachable at gitdiagram.com/owner/repo without pasting anything into a form.

The two-stage generation pipeline and its validation

Generation is not one model call that returns a picture. The README lays out seven steps, and the shape of them is the interesting part.

First, GitDiagram fetches the repository's default branch, recursive tree and README through the GitHub API. Truncated trees and oversized inputs are rejected before any model work begins, which caps the cost of a run on a very large repository by refusing it rather than truncating it silently. Then the first model stage streams a plain-English architecture explanation, which is why the interface can show text arriving while the graph is still being planned. The second stage returns a strict, size-bounded graph AST: groups, nodes, edges, shapes, labels, descriptions and repository paths.

That AST is where the design gets opinionated. The server validates identifiers, graph connectivity, limits and every linked path against the actual repository, and invalid output is retried with focused feedback. A deterministic compiler then converts the validated AST to Mermaid with total text escaping and GitHub-only links. In the browser, the source is sanitised, Mermaid renders in strict security mode, the resulting SVG is sanitised, and the link allowlist is enforced a second time. The README notes that the full Mermaid parser stays in the test suite as a compiler contract test but is deliberately not loaded into the production generation function, which keeps the server bundle small.

Two details are worth flagging. The model never writes Mermaid directly, so a malformed diagram is a compiler bug rather than a model failure. And links are restricted to GitHub, which means a diagram cannot send a reader to arbitrary external documentation.

Running GitDiagram locally

The README points to docs/dev-setup.md for exact prerequisites and environment details, so treat the commands below as the entry point rather than the whole setup. The project uses Bun, and the install sequence is four commands.

# clone the repository and install dependencies
git clone https://github.com/ahmedkhaleel2004/gitdiagram.git
cd gitdiagram
bun install
cp .env.example .env
bun run dev

After `bun run dev` the app is served on port 3000. The README says to open http://localhost:3000.

The README is direct about what `.env` needs: at minimum, configure R2, Upstash and one AI provider. A GitHub personal access token or GitHub App is optional but strongly recommended for higher GitHub API limits. The `.env.example` file names the keys. The storage and coordination block looks like this.

R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_PUBLIC_BUCKET=
R2_PRIVATE_BUCKET=
CACHE_KEY_SECRET=

UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=

OPENAI_API_KEY=
AI_PROVIDER=openai
OPENAI_MODEL=gpt-5.6-terra

The provider switch is `AI_PROVIDER`, which accepts `openai` or `openrouter`. If you choose OpenRouter, the example file expects `OPENROUTER_API_KEY`, `OPENROUTER_MODEL`, `OPENROUTER_SITE_URL` and `OPENROUTER_APP_NAME`. There are also optional per-IP throttle keys, `GENERATION_RATE_LIMIT_MAX` (8 in the example) and `GENERATION_RATE_LIMIT_WINDOW_SECONDS` (3600), which the file says apply to generations billed to the server's own key; callers supplying their own API key are not throttled.

Before opening a pull request, the README asks you to run the complete local gate.

bun run lint
bun run typecheck
bun run test
bun run build

The package.json also exposes `bun run check`, which chains lint and typecheck, and `bun run perf:budget` for performance budgets. A `Dockerfile` and `railway.json` are checked in, but the README describes them as a cold recovery recipe for disaster recovery rather than a second supported runtime.

Private repositories and where the token goes

Private repository support is a header toggle, not a server-side integration. You select Private Repos and provide a fine-grained GitHub personal access token that can read the target repository. The README states the token is sent only with the relevant same-origin request and is never embedded in public diagram links.

The storage side is separated as well. Successful public generations are R2 objects keyed by repository, while successful private generations live in a separate R2 namespace derived with a server-side secret. That secret is `CACHE_KEY_SECRET` in the example environment file. The practical consequence is that a private diagram is not simply a public diagram with a flag set; it is stored under a different key derivation, so a leak of the public bucket does not expose private artifacts by key guessing.

The limitation is the token scope itself. The README asks for a fine-grained token that can read the target repository, which means the token is a credential you are pasting into a browser form. There is no OAuth device flow described and no GitHub App installation flow described for the interactive path, even though the environment file lists GitHub App variables (`GITHUB_APP_ID`, `GITHUB_CLIENT_ID`, `GITHUB_PRIVATE_KEY`, `GITHUB_INSTALLATION_ID`) for server-side use. If your organisation forbids pasting repository-scoped tokens into a third-party page, the hosted service is the wrong entry point and the self-hosted deployment is the one to evaluate.

What GitDiagram will not do

The first hard boundary is the host. Everything in the README, the environment file and the repository layout assumes GitHub. There is no GitLab or Bitbucket integration described anywhere, and the compiler only emits GitHub links. A team whose repositories live on GitLab cannot use this tool as shipped.

The second boundary is input size. Truncated trees and oversized inputs are rejected before model work begins, so a very large monorepo may simply fail rather than produce a partial diagram. The README does not document a size threshold, and it does not describe a way to scope a run to a subdirectory, so the only lever a user has is picking a smaller repository.

The third is a failure mode you should expect in practice. Because the diagram is generated from a repository tree and a README, the quality of the output depends on the README describing the system. A repository with a thin or outdated README gives the model less to work with, and the validation step will not catch a diagram that is well formed but conceptually wrong. The README describes retries for invalid output; it does not describe any check that the diagram is a correct description of the software.

Finally, self-hosting is not a single-service deployment. The README lists Cloudflare R2 for artifacts, Upstash Redis for quota accounting, cancellation, locks and short-lived failure state, and OpenAI or OpenRouter for generation. Skipping any of them leaves generation non-functional, and the README does not document a local-disk or in-memory substitute for R2 or Upstash.

How it differs from Gitingest and from hand-drawn tools

The README credits Gitingest, by Romain Courtois, as the inspiration. That is the closest reference point and the difference is clean. Gitingest prepares a repository for a language model by producing a digest of the code, which you then read or feed to a model yourself. GitDiagram runs the model for you and returns a rendered graph with clickable links. If your goal is to paste a codebase into a chat window, Gitingest is the more direct tool. If your goal is a diagram you can look at and share, GitDiagram does the extra step.

The other comparison is with diagramming tools such as Eraser, which people search for alongside this project. Those are general-purpose drawing surfaces: you draw the architecture and maintain it by hand. GitDiagram derives the diagram from the repository, so the maintenance cost is close to zero, but so is your control over the result. You cannot hand-tune a node and have it survive the next generation. The README does describe export, though: copy the Mermaid source or download the rendered diagram as PNG, which is the intended way to take the output somewhere else and edit it there.

The streaming behaviour is also a real difference from a batch tool. Because the explanation streams while the graph is planned, you start reading before the diagram exists. That matters on large repositories where a full run takes time, and it is the reason the API surface includes a separate cancel endpoint rather than a single blocking request.

Maintenance, licence and what a self-hosted upgrade costs

The repository is not archived, and the last push was on 2026-09-14, two days before this writing. That is a recent commit, and it is the only maintenance signal available here; no releases were retrieved, so there is no version history to reason about and the package version is still 0.1.0. Treat the project as one that is being worked on, without inferring a release cadence from a single push date.

The licence is MIT, according to the README badge and the LICENSE file in the repository root. MIT is permissive, so the licence itself is unlikely to be the deciding factor. What the licence does not cover is the cost of running the thing. Two of the three required services are metered: Cloudflare R2 for artifact storage and Upstash Redis for quota, locks and cancellation state, plus per-token billing from OpenAI or OpenRouter. The environment file exposes `OPENAI_COMPLIMENTARY_GATE_ENABLED`, `OPENAI_COMPLIMENTARY_DAILY_LIMIT_TOKENS` and `OPENAI_COMPLIMENTARY_MODEL_FAMILY`, which exist because the hosted deployment pays for generations made with its own key. A self-hosted deployment inherits the same shape of cost, and the per-IP throttle keys are the only described control over it.

Upgrading is a source-level affair. There is no release channel described, so you track the main branch, and the README gives a concrete gate to run before proposing changes: lint, typecheck, test and build. The Dockerfile pins `oven/bun:1.3.14-alpine` for the dependency stage and `node:22-alpine` for the build and runtime stages, and the comment in it explains why: Bun's Linux ARM64 worker can crash while Next runs its TypeScript build, so Bun handles the frozen dependency install while Node runs the build. That is a pinned, deliberate arrangement, and changing the base images without re-running the gate is the kind of upgrade that breaks quietly.

Editorial conclusion

Use gitdiagram.com if you want a diagram of a public repository without running anything, and use the self-hosted path only if you are ready to provision Cloudflare R2, Upstash Redis and an OpenAI or OpenRouter key, because generation will not run without all three. Skip it if you need a diagram of a GitLab project, or if you need a folder tree rather than a system-level graph. Before adopting it, check the licence file, confirm the AI provider and model you intend to use, and read docs/dev-setup.md for the environment variables the README only summarises.

Frequently asked questions

Official sources

1. ahmedkhaleel2004/gitdiagram on GitHub
2. Issues
3. License: MIT
4. Project website
5. README