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
- Architecture-first diagrams: converts a repository tree and README into a system-level graph instead of merely drawing folders.
- Interactive source links: click a component to open its real file or directory on GitHub.
- Streaming generation: see the explanation arrive while the graph is planned.
- Private repositories: provide a GitHub token locally in the browser; private artifacts use a separate protected storage namespace.
- Export: copy Mermaid source or download the rendered diagram as PNG.
- Provider choice: OpenAI by default, with OpenRouter available for self-hosted deployments.
Stack
- Application: Next.js 16 App Router, React 19, TypeScript, Tailwind CSS, and Radix UI
- Generation API: same-origin Next.js Route Handlers running on Vercel's Bun runtime
- Storage: Cloudflare R2 for diagram artifacts
- Coordination: Upstash Redis for quota accounting, cancellation, locks, and short-lived failure state
- AI: OpenAI or OpenRouter through
AI_PROVIDER
- Analytics: PostHog
- Deployment: Vercel is the only live runtime; an offline Railway/Docker recipe is retained for disaster recovery
There is no separate FastAPI implementation, Postgres database, or Neon runtime.
Production architecture
Vercel serves both the UI and the generation endpoints:
/api/generate/cost estimates a run after bounded GitHub ingestion, same-origin and rate limited./api/generate/stream streams Server-Sent Events for explanation and graph progress./api/generate/cancel records authenticated, same-origin cancellation signals./api/diagram-state reads and writes the persisted result contract./api/healthz provides a lightweight deployment health check.
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
- 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.
- The first model stage streams a plain-English architecture explanation.
- The second stage returns a strict, size-bounded graph AST: groups, nodes, edges, shapes, labels, descriptions, and repository paths.
- The server validates identifiers, graph connectivity, limits, and every linked path against the actual repository. Invalid output is retried with focused feedback.
- A deterministic compiler converts the validated AST to Mermaid with total text escaping and GitHub-only links.
- The browser sanitizes the source, renders Mermaid in strict security mode, sanitizes the resulting SVG, and enforces the link allowlist again.
- 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
- Successful public generations: R2 object keyed by repository
- Successful private generations: separate R2 namespace derived with a server-side secret
- Complimentary quota and active cancellation tokens: Upstash Redis
- Terminal failures without a saved artifact: short-lived Upstash state
- Concurrent writes: distributed lock plus newest-session-wins persistence
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.
ahmedkhaleel2004/gitdiagram