gitdiagram
Applicationahmedkhaleel2004/gitdiagram
Turns any GitHub repository into an interactive AI-generated architecture diagram.
Overview
GitDiagram is a web app that converts any public or private GitHub repository into an interactive system architecture diagram within seconds. It streams an AI-generated overview and graph, links components to real source files, and exports Mermaid or PNG. Built with Next.js, it supports private repos via local tokens and caches results to avoid regeneration.
README Preview
[](https://gitdiagram.com/)\n\n\n[](https://ko-fi.com/ahmedkhaleel2004)\n\n# GitDiagram\n\nTurn any public or private GitHub repository into an interactive architecture diagram in seconds.\n\nYou can also replace `hub` with `diagram` in a GitHub URL to open its diagram.\n\n> **Sponsor slot:** Reach developers while they are actively exploring codebases. [Sponsor GitDiagram](https://gitdiagram.com/sponsor).\n\n## Features\n\n- **Architecture-first diagrams:** converts a repository tree, README, and bounded source excerpts into a system-level graph instead of merely drawing folders.\n- **Interactive source links:** click a component to open its real file or directory on GitHub.\n- **Streaming generation:** see the explanation arrive while the graph is planned.\n- **Private repositories:** provide a GitHub token locally in the browser; private artifacts use a separate protected storage namespace.\n- **Export:** copy Mermaid source or download the rendered diagram as PNG.\n- **Provider choice:** OpenAI by default, with OpenRouter available for self-hosted deployments.\n\n## Stack\n\n- **Application:** Next.js 16 App Router, React 19, TypeScript, Tailwind CSS, and Radix UI\n- **Generation API:** same-origin Next.js Route Handlers running on Vercel's Bun runtime\n- **Storage:** Cloudflare R2 for diagram artifacts\n- **Coordination:** Upstash Redis for quota accounting, cancellation, locks, and short-lived failure state\n- **AI:** OpenAI or OpenRouter through `AI_PROVIDER`\n- **Analytics:** PostHog\n- **Deployment:** Vercel is the only live runtime; an offline Railway/Docker recipe is retained for disaster recovery\n\nThere is no separate FastAPI implementation, Postgres database, or Neon runtime.\n\n## Production architecture\n\nVercel serves both the UI and the generation endpoints:\n\n- `/api/generate/cost` estimates a run after bounded GitHub ingestion, same-origin and rate limited.\n- `/api/generate/stream` streams Server-Sent Events for explanation and graph progress
FAQ (3)
TroubleshootingWhy does GitDiagram show 'You exceeded your current quota, please check your plan and billing details' error even for new visitors?
This error is not caused by your own usage — it appears when GitDiagram's shared server-side OpenAI API quota is exhausted, which blocks all visitors including first-time users. The maintainer has confirmed the issue is fixed, so refresh gitdiagram.com and retry. If the hosted site hits quota limits again, self-host GitDiagram with your own API key: 1) git clone https://github.com/ahmedkhaleel2004/gitdiagram.git && cd gitdiagram 2) copy .env.example to .env and set your OPENAI_API_KEY 3) run docker compose up --build and open the local instance. Self-hosting bypasses the shared quota entirely since billing uses your own OpenAI account.
TroubleshootingHow to fix 'Syntax error in text' Mermaid version 11.4.1 error in GitDiagram?
This error occurs when GitDiagram's generated Mermaid diagram code contains invalid syntax for Mermaid v11.4.1. It is a transient generation failure, not a permanent bug. Workaround: retry submitting the same GitHub repository URL — multiple users confirmed the diagram generates successfully on a second attempt. If the error persists after several retries, the repository's structure may produce characters that break Mermaid parsing; try again later or check for a GitDiagram/Mermaid version update.
TroubleshootingHow to fix 'Syntax error in text' error in Mermaid version 11.4.1 when rendering LLM-generated diagrams?
The error occurs because the LLM occasionally generates Mermaid code that violates the syntax specification. Workaround: add an explicit constraint to the prompt, e.g. 'You must strictly adhere to the official Mermaid syntax and output only valid Mermaid code compatible with version 11.4.1. Do not include explanatory text outside the diagram block.' Also remind the model to quote node labels containing special characters (parentheses, brackets, slashes), use valid arrow syntax (-->, -->|label|), and avoid unsupported characters in node IDs. If errors persist, validate the generated code in the Mermaid Live Editor (https://mermaid.live) to pinpoint the failing line before rendering.