DEV Community

Cover image for How to generate an architecture diagram from a GitHub repo
Raghav Chamadiya for repowise

Posted on Originally published at repowise.dev AI-assisted

How to generate an architecture diagram from a GitHub repo

TL;DR

  • To generate an architecture diagram from a GitHub repo, paste the repo URL into GitDiagram, Eraser or repowise, or run repowise init --index-only and repowise export --format structurizr on a local checkout.
  • GitDiagram and Eraser have a model read a sample of the code and draw the system. Parsed graphs such as repowise, Madge and pydeps resolve every import.
  • Checked edge by edge against Flask's 24 modules and 78 runtime import edges, the GitDiagram drawing of Flask left out 9 modules, including globals.py (imported by 12 Flask modules) and helpers.py (imported by 9).

This post first appeared on the repowise blog. I am posting it here because the question I tested comes up a lot on dev.to: if a tool draws your repo for you, how much of the repo is actually in the picture?

To generate an architecture diagram from a GitHub repo, paste the repo URL into a generator: GitDiagram, Eraser or repowise. GitDiagram and Eraser use a model to read the file tree, README and sampled source, then draw the system. repowise parses every import instead. The drawing is easier to read. The parsed graph is complete, and you can check every edge.

Tool How it builds the diagram Public repo without sign-up Private repos Stays current Price to start
GitDiagram A model reads the file tree, README and sampled source excerpts, returns a graph, the server checks every linked path exists Yes, swap hub for diagram in the GitHub URL Yes, with a GitHub token Cached per repo, you regenerate it Free hosted, MIT licensed, self-hostable with your own model key
Eraser A model scans the files your prompt points it at and draws the diagram you described Git Diagrammer page takes a public URL, diagrams open in the Eraser app Yes, by connecting the repo Eraserbot comments an updated diagram on PRs that touch monitored files Free plan has 3 AI diagrams, Starter $20/member/month or $15 billed yearly
repowise Parses source into syntax trees, resolves imports into a file graph, groups it into layers and containers, adds git history Yes, paste the URL on the homepage Yes, through a read-only GitHub App on Pro Re-indexed on every push on Pro Free for public repos and for the open-source CLI

I build repowise, so read the rest knowing that. The test below checks a published diagram against the parsed graph, and the method is at the end so you can repeat it.

How to generate the diagram, step by step

Each tool takes one URL or one command. As of October 2026:

  1. GitDiagram: open a public repo on GitHub and replace hub with diagram in the address (github.com/pallets/flask becomes gitdiagram.com/pallets/flask). Export PNG or Mermaid source from the page. For a private repo, add a GitHub token in the interface (source).
  2. Eraser: connect the repo or use the Git Diagrammer page, name the folders you want drawn, and edit the result in the Eraser app (pricing).
  3. repowise: paste a public URL on the repowise homepage, or index a local checkout and export the architecture as Structurizr DSL:
pip install repowise
repowise init --index-only
repowise export --format structurizr --standalone
Enter fullscreen mode Exit fullscreen mode

--index-only needs no API key. The export is deterministic, built from the existing graph, and --standalone writes a complete workspace.dsl you can render in any Structurizr tool (export docs).

Two different ways to draw a repo

There are two families of tools behind the "repo to diagram" search, and they answer different questions.

The first family asks a model to describe the system. You give it the repository, it reads what fits in its context window, and it returns boxes and arrows that tell a story: the request comes in here, goes through this, ends up there. GitDiagram and Eraser are in this family, as is any coding agent you ask to "draw the architecture as Mermaid".

The second family parses the code. A parser turns every file into a syntax tree, finds each import, and resolves it to the file it points at. The result is a dependency graph that holds every file and every import edge, with no judgement about which ones matter. Madge, dependency-cruiser and pydeps are single-language versions of this. repowise does it across 28 languages and then groups the graph into layers you can read.

The first family is better at telling the story of the code and the second at being complete, so most arguments about "which diagram tool is accurate" compare one family's strength with the other family's weakness.

The test: Flask, one drawing, one parse

I picked pallets/flask because it is small enough to check by hand (24 Python modules under src/flask) and popular enough that GitDiagram already had a diagram for it, so I did not need to spend anyone's quota generating one.

What I did, on 6 October 2026:

  1. Opened gitdiagram.com/pallets/flask and pulled the Mermaid source out of the page.
  2. Cloned Flask at commit 2a8a38b, the commit repowise has indexed for its Flask page, and wrote a 40-line script with Python's ast module that lists every import between Flask's own modules. Imports inside if TYPE_CHECKING: blocks are kept separate, because they never run.
  3. Compared the two, edge by edge.

I did not run Eraser on Flask. Its codebase diagrams start from a prompt you write and need an Eraser account, and I wanted to compare outputs nobody had steered. I describe Eraser from its documentation below.

What the GitDiagram drawing gets right

The diagram is a good one. It shows 15 Flask modules plus six external pieces (HTTP client, WSGI server, your application, Werkzeug, Jinja2, itsdangerous), each module linked to its file on GitHub. The flow it tells is correct: the WSGI server calls the Flask app, the app dispatches to your view function, templates render through Jinja2, sessions sign cookies with itsdangerous.

The written overview that comes with it is careful: for cli.py and wrappers.py it says the file's body "was not sampled", which is a useful thing for a model to admit.

The drawing also caught a dependency that an import graph cannot see. The diagram has an edge from the JSON provider to the Flask app labelled "creates response". src/flask/json/provider.py does not import the app at runtime. It holds a weak reference to the app and calls self._app.response_class(...) on line 105. That dependency only shows up if you read the code, and the model read it.

What it leaves out

The parsed graph has 24 modules and 78 runtime import edges between them. Measured against that:

  • The two most-imported modules are missing. globals.py is imported by 12 other Flask modules and helpers.py by 9. Neither appears in the diagram. If you are about to change helpers.py, the drawing gives you no hint that nine files depend on it.
  • Nine modules are missing in total: globals.py, helpers.py, config.py, debughelpers.py, logging.py, testing.py, typing.py, views.py and the top-level blueprints.py. The diagram's "Blueprint Registration" box links to sansio/blueprints.py, but the Blueprint class you import from flask lives in src/flask/blueprints.py, which subclasses the sans-IO one.
  • Some real edges are absent. app.py imports sessions.py at runtime, but in the drawing nothing points at the session box except your own application. wrappers.py sits in the diagram with no edges at all, while in the code app.py imports it and it imports json, helpers and debughelpers.

The drawing is a curated summary, and a summary has to drop things. The problem is that you cannot tell from the picture what was dropped. A box with no arrows can mean "nothing depends on this" or "the model did not sample it", and those two readings lead to very different decisions.

The Mermaid below is the part of the parsed graph that the drawing does not show. You can paste it into any Markdown viewer that renders Mermaid.

flowchart LR
  app[app.py] --> sessions[sessions.py]
  app --> wrappers[wrappers.py]
  app --> globals[globals.py]
  app --> helpers[helpers.py]
  ctx[ctx.py] --> globals
  ctx --> helpers
  templating[templating.py] --> globals
  templating --> helpers
  wrappers --> helpers
  wrappers --> json[json/__init__.py]
  json --> globals
  cli[cli.py] --> globals
  cli --> helpers
  blueprints[blueprints.py] --> sansio_bp[sansio/blueprints.py]
  blueprints --> helpers
  sessions --> tag[json/tag.py]

The parsed side

repowise parses every file, so nothing is sampled out. Its Flask architecture page groups the repo into four layers: Application (29 files, including all of src/flask), Config (10), Docs and Tooling (28) and Test (61). Zooming into the file graph puts globals.py and helpers.py at the centre, which is where the 12 and 9 importers say they should be.

The repowise architecture map of the repowise repository itself, showing module clusters sized by file count with weighted edges between them

The same map for any repo shows communities of files, the heaviest edges between them, and a trace tool that finds the path between two files.

I also downloaded the Structurizr DSL export for Flask (a text format for C4 architecture diagrams). It describes Flask as one Python container with components for flask (25 files, 496 symbols), tests (52 files) and the three example apps. One edge in it, from the flask source component to tests, has no matching import in src/flask, which my script confirmed. Because each edge comes from a resolved import, you can trace it to its line and judge it yourself, which is the property a model's omission lacks.

Eraser, from its docs

Eraser's codebase diagrams start from a prompt. Its docs give examples like asking for a cloud architecture diagram of the services under a folder, and recommend naming specific paths to improve accuracy. That makes it good for a particular slice you already know about (the Terraform under infra/, the Prisma schema, one service's request flow), and less suited to "show me this repo I have never seen".

Eraser has strengths the other two tools lack. Its diagrams are editable in a proper diagramming app, by hand or as diagram-as-code. And Eraserbot can watch files: when a pull request touches them, it comments an updated diagram on the PR within a minute or two. Eraserbot needs a connected repo and usage-based pricing turned on. The free plan includes 3 AI diagrams. Starter is $15 per member per month billed yearly ($20 monthly) with 40, and Business is $45 billed yearly ($60 monthly) with 250.

Choosing a tool

Use GitDiagram when you want to understand an unfamiliar public repo in the next five minutes. It is free and fast, its boxes link to real files, and the newer pipeline reads sampled source files as well as the README. Treat it as an introduction written by a smart colleague who skimmed the code. It now also has its own MCP server at gitdiagram.com/mcp, so a coding agent can fetch a public repo's diagram directly.

Use Eraser when the diagram is a deliverable: a design review, a doc page, a slide. You decide what it should show, then edit it until it is right, and Eraserbot keeps that specific diagram from drifting.

Use repowise or another parsed graph when the diagram feeds a decision. Before you change helpers.py, you want all nine dependents, not the five that made it into a summary. Single-language tools like Madge or pydeps give you that for free. repowise gives it across languages, with layers, ownership and change history on the same page, and re-indexes on every push on Pro so the graph does not go stale.

In practice I use both: the drawing to learn what the authors meant, and the graph to check what the code actually does. If neither family fits, this comparison of codebase visualization tools covers more options.

Pitfalls

  • Reading a box with no arrows as "unused". In a model-drawn diagram it can mean the file was not sampled. Check the file's importers in a parsed graph.
  • Treating imports as the whole story. Calls through object references, such as Flask's JSON provider reaching its app, are not imports. Read those in the code.
  • Trusting a stale picture. A cached diagram does not follow your commits. Regenerate it, or use a tool that re-indexes on push.
  • Pasting a huge repo into a model. Only a sample fits, so omissions grow with repo size.

How I measured

  • GitDiagram: the cached diagram at gitdiagram.com/pallets/flask, Mermaid source read from the page on 6 October 2026. I do not know which Flask commit it was generated from. Its file links point at main. Between repowise's indexed commit (2a8a38b, 11 August 2026) and Flask's main on 8 September, only two lines changed in app.py and helpers.py, with no new or removed modules.
  • Parsed graph: Python's ast over the 24 .py files in src/flask at 2a8a38b. Relative and absolute imports of Flask's own modules were resolved to files. Imports inside TYPE_CHECKING blocks were excluded from the 78 runtime edges. This counts imports only, so calls through object references (like the JSON provider's) are not in it.
  • repowise: the public Flask page and the Structurizr DSL export from api.repowise.dev, snapshot of commit 2a8a38b.
  • This test covers one repo, Flask, which is small enough to check by hand.

Which repo would you want checked this way next?

FAQ

How do I generate an architecture diagram from source code?
Either have a model read the code and draw it (GitDiagram, Eraser, or a coding agent asked for Mermaid), or parse the imports into a dependency graph (repowise, Madge, dependency-cruiser, pydeps). With repowise, repowise init --index-only followed by repowise export --format structurizr --standalone writes a workspace.dsl you can render in any Structurizr tool.

What is a GitHub diagram generator?
A tool that takes a GitHub repo URL and returns a diagram of the code. GitDiagram works by swapping hub for diagram in a public repo's URL, and repowise draws the architecture of any public repo you paste on its homepage.

Can I generate a UML diagram from code?
Yes, for class diagrams: tools such as pyreverse (part of pylint) build UML class and package diagrams from Python source. The tools compared above draw module dependencies and architecture layers, which is a different view from UML classes.

Top comments (0)