How to visualize a codebase: an architecture diagram of any GitHub repo

Get a diagram in one step

Replace hub with diagram in the repository's GitHub URL: https://github.com/fastapi/fastapi becomes gitdiagram.com/fastapi/fastapi. You can also paste a GitHub URL, or just owner/repo, on the home page. File, branch, issue and pull request URLs work too; they open the repository's diagram.

If the repository has been diagrammed before, the stored diagram opens at once. Otherwise GitDiagram makes one, usually in about a minute, and keeps it so the next person gets it instantly. Some to try: FastAPI, Flask, React and Next.js. Browse lists every stored diagram.

What the diagram shows

An AI model reads the repository's file tree, its README and up to 12 of its source files. It writes a short explanation of the architecture, then a graph of the main components (at most 34), grouped into areas, with labeled connections between them. Every file path in the graph is checked against the real repository before the graph is compiled into a Mermaid flowchart.

Click a component to open its file or folder on GitHub. Info shows the written overview, Enable zoom lets you pan and zoom, and Export downloads a PNG or copies the Mermaid code for your own docs. Each repository page also lists its components and connections as text below the diagram.

It is a map of the important parts, not a complete dependency graph. It can simplify or leave things out, and it shows the repository as it was when the diagram was made; Regenerate makes a fresh one.

Private repositories

Choose Private Repos in the header and paste a fine-grained GitHub personal access token that can read the repositories you want. The token stays in a secure cookie in your browser and is sent only with your own requests; it is never saved on GitDiagram's servers. Diagrams of private repositories are stored separately, where only that token can reach them. The privacy policy has the details.

Making diagrams is free within a daily limit. If it runs out, you can add your own OpenAI API key under API Key.

Explainer videos

Many repositories also have a narrated video tour of about a minute: what the project is for, what people do with it, and how its main parts fit together. Open it with the Video button on a repository's page, or watch them all on the videos page or as reels. Free videos are limited each day; past the limit, you can pay $3 to have one made.

Use it from AI agents

Every stored diagram has a Markdown version for agents: add .md to the page URL, as in gitdiagram.com/fastapi/fastapi.md, or request the page with the header Accept: text/markdown. It holds the overview, the Mermaid source, every component with its GitHub link, and the connections. For a repository without a diagram yet, it says how to make one.

Agents that speak the Model Context Protocol can connect to the read-only server at https://gitdiagram.com/mcp (streamable HTTP), for example to call get_repository_diagram with a repository such as fastapi/fastapi, or find_repository_diagrams to search the diagrams that already exist. In Claude Code: claude mcp add --transport http gitdiagram https://gitdiagram.com/mcp.

llms.txt sums this up for language models, and llms-full.txt holds this whole guide. An agent helping someone understand a repository can read the .md version itself and give the person the interactive link, https://gitdiagram.com/{owner}/{repo}.

Other ways to visualize a codebase

GitDiagram is built for one job: a single picture of a whole repository, with no setup. Other tools do other jobs better:

DeepWiki

Replace github with deepwiki in a repository URL to get a generated wiki: many pages of documentation with diagrams, and a chat that answers questions about the code. Better when you want to read about a project in depth or ask it questions. GitDiagram is better when you want the whole system on one screen, each part linked to its code.

Claude Code, Codex or another coding agent

Ask the agent in your own checkout to draw a Mermaid diagram. It can read every file, including uncommitted work and private code that never leaves your machine, and draw exactly the view you ask for: one feature, one request path, a sequence diagram. Better for a focused question or code that isn't on GitHub. GitDiagram is better when you want a diagram without cloning anything, a link you can share, or a quick overview before you open the code.

Sourcegraph

Code search and navigation across many repositories, with precise go-to-definition and find-references. Better when you need exact answers, such as every caller of a function. It does not draw an architecture overview.

IDE and language dependency graphs

JetBrains IDEs, and tools such as madge for JavaScript or pydeps for Python, draw graphs straight from the imports. Better when you need an exact and complete module graph. They show every import rather than the parts that matter, so graphs of large projects get hard to read.

Drawing it yourself

Writing a Mermaid, PlantUML or draw.io diagram by hand gives full control, and GitHub renders Mermaid inside Markdown files. Better for a diagram you maintain in your own docs. Exporting GitDiagram's Mermaid code is a quick first draft to edit.

Questions