How to add an architecture diagram to your GitHub README

Step by step

1. Make the diagram. Open gitdiagram.com/{owner}/{repo} for your repository. For a private repository, give it read access first (how).
2. Pick the form. Export offers four. Copy Mermaid gives editable text that GitHub renders and that shows up in diffs. README picture copies Markdown for an image at gitdiagram.com/{owner}/{repo}/diagram.png that links to the interactive diagram and follows the latest diagram. Download PNG gives a fixed image to commit. README badge copies a small badge that opens the diagram.
3. Trim it for readers. A README diagram is for someone deciding whether and where to contribute, so keep the groups and the main path and drop the rest. Rename boxes to the words your team uses. The exported code links each box to its file with click lines; keep or delete them.
4. Paste it. Put the code between a line with three backticks and mermaid, and a closing line of three backticks, usually under an Architecture heading. GitHub renders it in the README, issues, pull requests and wikis.
5. Keep it current. Edit the Mermaid in the pull request that changes the architecture, or regenerate the diagram after a big change. A README picture updates by itself when the diagram is regenerated.

Example: GitDiagram's own README diagram

GitDiagram's diagram of its own repository has 26 parts in 5 groups (Diagram experience, Diagram generation, Repository browsing, Explainer videos, Sponsorship) and 18 connections. For a README you would keep one group, as in the trimmed excerpt below: the exported code, with the other groups and the click and styling lines removed.

## Architecture

```mermaid
flowchart TD
subgraph group_generation["Diagram generation"]
  node_stream_api["Generation stream<br/>[route.ts]"]
  node_admission["Request admission"]
  node_github_ingest["GitHub ingestion<br/>[github.ts]"]
  node_source_context["Source context<br/>[source-context.ts]"]
  node_model_stream["Model streaming<br/>[openai.ts]"]
  node_graph_compile["Graph compilation<br/>[graph.ts]"]
end
node_stream_api -->|"admits request"| node_admission
node_stream_api -->|"fetches repository"| node_github_ingest
node_stream_api -->|"fetches sources"| node_source_context
node_stream_api -->|"streams completion"| node_model_stream
node_stream_api -->|"compiles graph"| node_graph_compile
```

Other ways to make a README diagram

Writing the Mermaid yourself gives full control and needs no tool at all. draw.io and Excalidraw are better for a hand-designed picture, saved as an image in the repository. Structurizr keeps a C4 model as code when a team wants a maintained, formal architecture. GitHub Next's repo-visualizer Action draws an SVG of the folder structure on every push, but it shows files and sizes, not architecture, and the repository is archived.

GitDiagram's diagram is made by an AI model from the file tree, the README and up to 12 source files. It is a map of the important parts, at most 34 of them, not a complete dependency graph: it can simplify or leave things out, every linked path is checked against the real repository, and it shows the repository as it was when the diagram was made (Regenerate makes a fresh one).

Questions

Sources

Checked on November 9, 2026. Products change: if something here is out of date, open an issue.

• GitHub Docs: Creating diagrams (Mermaid in Markdown)
• Mermaid documentation
• githubocto/repo-visualizer (archived)
• The C4 model