gitdiagram README

The project's README from github.com/ahmedkhaleel2004/gitdiagram. As one markdown file: README.md.

GitDiagram front page

License Ko-fi

GitDiagram

Turn any public or private GitHub repository into an interactive architecture diagram in seconds.

You can also replace hub with diagram in a GitHub URL to open its diagram.

Sponsor slot: Reach developers while they are actively exploring codebases. Sponsor GitDiagram.

Features

Stack

There is no separate FastAPI implementation, Postgres database, or Neon runtime.

Production architecture

Vercel serves both the UI and the generation endpoints:

Long-running generation uses a 300-second Vercel function budget with a shorter application deadline so quota reconciliation and persistence still have time to finish. Requests use explicit upstream deadlines, retries, structured logs, heartbeats, and distributed cancellation rather than process-local state.

The same Next.js application can also build into a minimal, non-root standalone Docker image for Railway. No Railway service, source connection, or Railway domain is kept live. The checked-in Dockerfile and railway.json are a cold recovery recipe that can recreate the full application later without reviving a second backend implementation. See docs/deployment-failover.md.

How generation works

  1. GitDiagram fetches the repository's default branch, recursive tree, and README through the GitHub API. Truncated trees and oversized inputs are rejected before model work begins.
  2. The first model stage streams a plain-English architecture explanation.
  3. The second stage returns a strict, size-bounded graph AST: groups, nodes, edges, shapes, labels, descriptions, and repository paths.
  4. The server validates identifiers, graph connectivity, limits, and every linked path against the actual repository. Invalid output is retried with focused feedback.
  5. A deterministic compiler converts the validated AST to Mermaid with total text escaping and GitHub-only links.
  6. The browser sanitizes the source, renders Mermaid in strict security mode, sanitizes the resulting SVG, and enforces the link allowlist again.
  7. Successful artifacts and terminal audit state are persisted so later visits can reopen the diagram without another model call.

The full Mermaid parser remains in the test suite as a compiler contract test. It is deliberately not loaded into the production generation function, keeping the server bundle small without weakening diagram validation or browser safety.

State

Private repositories

Select Private Repos in the header and provide a fine-grained GitHub personal access token that can read the target repository. The token is sent only with the relevant same-origin request and is never embedded in public diagram links.

Local development

For exact prerequisites and environment details, see docs/dev-setup.md.

git clone https://github.com/ahmedkhaleel2004/gitdiagram.git
cd gitdiagram
bun install
cp .env.example .env
bun run dev

Open http://localhost:3000.

At minimum, configure R2, Upstash, and one AI provider in .env. A GitHub PAT or GitHub App is optional but strongly recommended for higher GitHub API limits.

Run the complete local gate before opening a pull request:

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

Contributing

Contributions are welcome. Please open an issue or pull request with a focused description and verification notes.

Acknowledgements

Inspired by Romain Courtois's Gitingest.

gitdiagram (ahmedkhaleel2004/gitdiagram)

github
Searching Database…

18.3K ·GitHub
Gitdiagram
What is this?GitDiagram turns any public or private GitHub repository into an interactive architecture diagram in seconds. You can also replace 'hub' with 'diagram' in any GitHub URL to open its diagram.
Is this a website I visit, or something I have to install?It's a web app — nothing to install. It converts the repository tree and README into a system-level graph of components and edges rather than drawn folders, and every node links to its real source on GitHub.
How do I get a diagram for a repository, and what happens under the hood?Swap 'hub' for 'diagram' in any GitHub URL. It fetches the repo tree and README via the GitHub API, streams a plain-English architecture explanation, then renders a validated interactive Mermaid graph.
Do I need my own OpenAI API key to use it?Not on the hosted site: OpenAI is used by default (OpenRouter for self-hosted) and a complimentary quota is included. Local development needs more — at minimum R2, Upstash, and one AI provider in .env.
Does it work on every repository, or are there limits?Yes: truncated trees and oversized inputs are rejected before model work begins, and generation must fit a 300-second Vercel function budget.
Can I run GitDiagram on my own server instead of the hosted site?Vercel is the only live runtime, but the repo keeps a recovery recipe: the same Next.js app builds into a minimal non-root Docker image for Railway via the checked-in Dockerfile and railway.json.
Can it diagram private repositories, and what happens to my GitHub token?Yes — pick Private Repos and provide a fine-grained GitHub personal access token. It travels only with the same-origin request, is never embedded in public links, and private artifacts get a separate R2 namespace.
How does it stop the AI from producing broken or wrong diagrams?Model output is validated before you see it: the server checks identifiers, graph connectivity, limits and every linked path against the actual repository, retrying invalid output with focused feedback, and the browser renders sanitized Mermaid in strict security mode.
Do I trigger a fresh AI run every time I reopen a diagram?No. Successful artifacts are persisted to Cloudflare R2 — keyed by repository, with private ones in a separate namespace — so later visits reopen the saved diagram without another model call.
What can I actually do with the finished diagram?Click any component to open its real file or directory on GitHub, copy the Mermaid source, or download the rendered diagram as a PNG.
What is GitDiagram built with?Next.js 16 App Router, React 19, TypeScript, Tailwind CSS and Radix UI, with generation endpoints on Vercel's Bun runtime. Cloudflare R2 stores artifacts, Upstash Redis handles quotas and locks, and the AI provider is OpenAI or OpenRouter.
What are similar projects?next-ai-draw-io, archify, oh-my-mermaid, deepwiki-open, whirl, chatbot, crm, svg-diagram
Which topics is it in?gemini-cli-extension, architecture-diagram, mermaid, code, software-architecture, diagrams, system-design, openrouter, vercel, architecture, visualization, tailwindcss
Creator
ahmedkhaleel2004
Size
14.3 MB
Stars
18.3K
Updated
CommitOct 14
Age
1y
Commits · 90 Days