GitDiagram: Interactive Architecture Diagrams and Explainer Videos for GitHub Repositories

What GitDiagram Does and Who It Is For

GitDiagram takes a GitHub repository URL and produces an interactive diagram of the project's architecture. Each component in the diagram links to its corresponding file or directory in the repository, so a developer can click a node and jump directly to the source rather than navigating a file tree manually.

The README describes the shortcut clearly: replace `hub` with `diagram` in any GitHub URL. A repository at `github.com/owner/repo` becomes `gitdiagram.com/owner/repo`. The hosted service requires no account for public repositories.

The primary audience is developers who encounter an unfamiliar codebase and want a structural overview faster than reading through a file tree or searching for documentation. It is also useful for maintainers who want a shareable diagram of their own project without writing one by hand in Mermaid syntax.

Diagrams can be exported as PNG or as Mermaid source text, so the output is not locked into the gitdiagram.com viewer. A developer who wants to embed the diagram in documentation can copy the Mermaid source and paste it into any Mermaid-compatible renderer.

Explainer Videos: A Second Output Format

GitDiagram added a video output format that produces a narrated video of roughly one minute. According to the README, the video starts with what the project is for and what people do with it, then shows briefly how its main parts fit together and one decision under the hood.

Videos are available by appending `/video` to any diagram URL, such as `gitdiagram.com/owner/repo/video`. A gallery of existing videos is at `gitdiagram.com/videos`. MP4 download is available in landscape or 9:16 vertical format, with captions burned in.

At the time the README was written, making new videos was in early access. Anyone can watch videos that already exist. This two-tier access means a viewer can watch a video for any repository that has one, but generating a new video requires early access.

For self-hosted deployments, video generation is off by default. Enabling it requires setting these variables in `.env`:

VIDEO_EXPLAINER_ENABLED=1
NEXT_PUBLIC_VIDEO_EXPLAINER=1
ANTHROPIC_API_KEY=
OPENAI_API_KEY=
OPENROUTER_API_KEY=

The README notes that `OPENROUTER_API_KEY` is specifically needed for the narrator's voice, which uses Gemini 3.8 Flash TTS via OpenRouter. The script and scene authoring for the video uses either Claude (via `ANTHROPIC_API_KEY`) or GPT (via `OPENAI_API_KEY`). All three keys are therefore needed to run video generation end to end on a self-hosted instance.

Running GitDiagram Locally

The README requires Bun, Cloudflare R2, Upstash Redis, and an OpenAI or OpenRouter API key before starting. Clone the repository and install dependencies:

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

After filling in `.env` with credentials from the configuration guide at `docs/dev-setup.md`, start the development server:

bun run dev

The application opens at `localhost:3000`. The `.env.example` file shows the required variables: Cloudflare R2 credentials (`R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_PUBLIC_BUCKET`, `R2_PRIVATE_BUCKET`), Upstash Redis credentials, and an OpenAI or OpenRouter API key. A `CACHE_KEY_SECRET` is also required.

The `AI_PROVIDER` variable selects the generation backend: `openai` or `openrouter`. The default model when using OpenAI is controlled by `OPENAI_MODEL`. When using OpenRouter, the model is set with `OPENROUTER_MODEL`.

R2 serves two buckets: a public bucket for diagrams that can be served directly, and a private bucket whose purpose the `.env.example` does not explain beyond naming it. Redis provides caching so that the same repository does not need to be regenerated on every visit. The `CACHE_KEY_SECRET` allows the owner to bust cached entries by rotating the key.

The package.json `check` script runs linting and type checking together:

bun run check

This runs `eslint` across `.js`, `.jsx`, `.ts`, and `.tsx` files with `--max-warnings 0`, meaning any lint warning fails the check. The README's setup guide at `docs/dev-setup.md` documents verification steps before submitting a pull request.

Docker Deployment and the Dockerfile Design

The repository includes a Dockerfile that uses a multi-stage build. The first stage uses `oven/bun:1.3.14-slim` for dependency installation. The builder stage switches to `node:22-bookworm-slim` because, as the Dockerfile comment explains, Bun's Linux ARM64 worker can crash during a Next.js TypeScript build.

The runner stage uses Debian rather than Alpine because, according to a comment in the Dockerfile, MP4 and poster renders run Chromium, which needs glibc rather than musl. The `HOSTNAME` is set to `0.0.0.0` and `PORT` to `3000`. The Dockerfile notes that containers lack user namespaces for Chrome's sandbox, so the same flags used on Vercel apply.

A Railway deployment fallback is documented in `docs/deployment-failover.md`, and a `railway.json` file is present at the repository root.

For the video feature, the Dockerfile handles `NEXT_PUBLIC_*` variables as build arguments since they are compiled into the client at build time. The Dockerfile comment explains that `.env` files never reach the Docker image, so these values must come in as build arguments. Railway passes a service variable with the same name as each `ARG` automatically. Without these arguments, the video controls build with video switched off and live presence unset:

ARG NEXT_PUBLIC_POSTHOG_KEY
ARG NEXT_PUBLIC_PRESENCE_URL
ARG NEXT_PUBLIC_VIDEO_EXPLAINER

Private Repository Support and Rate Limits

Private repositories require a GitHub token, provided via the "Private Repos" button in the application header. The `.env.example` shows two rate-limit controls for the hosted deployment.

The first is a per-IP throttle on generations billed to the server's own key:

GENERATION_RATE_LIMIT_MAX=8
GENERATION_RATE_LIMIT_WINDOW_SECONDS=3600

Callers who supply their own API key are not throttled by this limit. A second, looser limit applies to infrastructure calls such as `/api/generate/cost` and `/stream` for every caller regardless of key:

GENERATION_INFRASTRUCTURE_RATE_LIMIT_MAX=60
GENERATION_INFRASTRUCTURE_RATE_LIMIT_WINDOW_SECONDS=3600

The `.env.example` comment explains that this looser throttle bounds GitHub and session work rather than diagram generation itself. There is also an optional daily token cap for complimentary usage, controlled by `OPENAI_COMPLIMENTARY_GATE_ENABLED` and `OPENAI_COMPLIMENTARY_DAILY_LIMIT_TOKENS`. Setting `OPENAI_COMPLIMENTARY_GATE_ENABLED=false` removes the application-level daily quota and lets requests run against the server account's available credits without a cap.

Technology Stack and a Key Limitation

GitDiagram is built with Next.js, React, TypeScript, Tailwind CSS, and Mermaid for diagram rendering. Video generation uses Claude or GPT for script and scene authoring and OpenRouter (Gemini 3.8 Flash TTS) for the voice. The package.json lists `@anthropic-ai/sdk` and `openai` as runtime dependencies alongside `mermaid` at version 12.

The test suite uses Vitest. The package.json includes a `test` script that runs `vitest run`, and a `typecheck` script using TypeScript 7. A pre-commit hook is configured through `.githooks/`.

The diagrams are AI-generated and rely on the quality of the repository's file structure and README. The generation pipeline reads the file tree and key files to build the diagram, but the README does not document how it handles repositories with minimal documentation or unusual layouts. Output quality for sparse repositories or private repositories with little context may vary.

For developers who want to self-host on a budget, the full dependency stack is a genuine barrier: Cloudflare R2 for storage, Upstash Redis for caching, and at least one LLM API key are all required before the application starts. There is no mode that runs without external dependencies.

A real alternative to GitDiagram for architecture visualization is Gitingest (gitingest.com), which the README credits as the inspiration. Gitingest converts repository contents into a flat text representation for pasting into AI chat context, while GitDiagram produces an interactive visual diagram. The two tools solve related but different problems: Gitingest prepares a repository for AI analysis, GitDiagram visualizes the structure for human navigation.

The last push to the repository was on 2026-09-26, and the repository is not archived.

Editorial conclusion

GitDiagram is a practical tool for developers who regularly approach unfamiliar repositories and want a visual map before reading code. It is not the right tool if your organization requires all code analysis to stay within a private environment, since the hosted service at gitdiagram.com sends repository contents to an external AI provider. Self-hosting is possible but requires Bun, Cloudflare R2, Upstash Redis, and either an OpenAI or OpenRouter API key, which means the infrastructure cost is not trivial. Start by replacing 'hub' with 'diagram' in any public GitHub URL to see whether the diagram quality suits your use case before committing to a self-hosted deployment.

Frequently asked questions

Official sources

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