GitHub repo to architecture diagram: connect once, redraw when main moves

Paste owner and repository, or paste the browser URL of the repo. Both are accepted, and a trailing .git, a query string, or a stray slash is stripped before anything is stored. A public repository needs no token at all.

A private repository takes a fine-grained personal access token scoped to that one repository, with the repository permission Contents set to Read-only. GitHub pairs that with Metadata Read-only automatically, and those two are the whole requirement. A classic token carrying the repo scope also works, but that scope includes write access, so the fine-grained token is the better trade for a tool that only ever reads.

The credential is proven before it is stored: Datadef lists the branches and tags of the repository, which is the cheapest possible check that the token works and can see the repo. It is then encrypted at rest with AES-256-GCM and a fresh initialization vector, and only its last four characters are ever shown again.

Then pick the ref. Each diagram tracks exactly one branch or tag, and one connection can back several diagrams: main for the living picture, a release tag for the record of what shipped. Datadef reads the repository at that ref, proposes what the diagram should show based on the file counts it found, and generates a canvas plus an architecture.md.

Connection
  provider   github
  repo       acme/platform          (or https://github.com/acme/platform)
  token      fine-grained PAT, Contents: Read-only   (public repo: none)

Diagram
  ref        branch main            (or tag v2.4.0)
  output     canvas + architecture.md, regenerated on sync

File listing goes through the git trees API with recursive=1, and GitHub documents the ceiling on that call precisely: 100,000 entries and 7 MB, past which the response carries truncated set to true and is silently missing paths. A tool that reads the array and ignores the flag loses whole directories without ever saying so. When the flag comes back, Datadef throws that response away and walks the tree breadth-first instead, one request per directory object, bounded at 60 requests and 20,000 entries.

Tags are dereferenced properly. A lightweight tag points straight at a commit, while an annotated or signed tag points at a tag object that has to be resolved one step further to reach the commit it wraps. Tracking v2.4.0 therefore reads the tree of the commit the tag was cut from, which is what you meant when you picked the tag.

Two boundaries up front. The supported hosts are github.com, gitlab.com, and dev.azure.com, and the form accepts no custom base URL, so GitHub Enterprise Server is not connectable yet. And anything between 1 MB and 100 MB comes back from the contents API with an empty content field and encoding set to none, which GitHub documents; the reader treats that as unreadable and moves on. Selection has already dropped anything over 400KB before the fetch, so in practice this only ever concerns generated bundles that carry no architecture.

A repository visualizer that runs once has one structural problem: the picture is true at the moment you click it, and after that it is a screenshot. GitDiagram turns a repo into an interactive Mermaid diagram in seconds, Swark draws one from inside VS Code using a model you already pay for, and both are good for a first look at unfamiliar code. Neither is watching the branch tomorrow.

Three mechanics separate a connection from a rerun. The first is a structure fingerprint: a SHA-256 of the material that actually feeds the diagram, kept as its first 32 hex characters. A commit that edits a README, adds a test, or reformats a comment moves the commit sha and leaves that fingerprint identical, so generation is skipped before a token is spent.

The second is continuity. When the structure genuinely changed, the previous diagram ids, labels, and zones are handed to the generator with an instruction to reuse everything that still exists, so adding one consumer reads as one new node rather than a new composition of the same system. The third is pinned positions: every sync records the coordinates it wrote for each node, and the next one treats anything sitting more than 12 pixels from its recorded spot as hand-placed, pinning it and restoring it after the new layout runs.

Back into the README, most of the time. One markdown image line renders the current diagram as a live embed that follows the canvas, so the picture at the top of the repo is the picture the last sync produced. Readers need no account.

The architecture.md that comes with it is plain markdown: an overview, a component inventory, the data flow, how the system deploys, and short notes per notable directory. On a public project it ships with the embed line already inside it, so the doc and the picture come from the same read of the same commit.

From the canvas the diagram behaves like any other Datadef diagram: editable, exportable as PNG or JPEG, shareable with the team. And your coding agent can bring it forward without opening the app, using the repo tools described in refresh a repo diagram from an agent.

• Repo to diagram: how repository sync works
• Embed diagrams in a GitHub README
• What a repo sync reads from your codebase
• Can AI draw a diagram from a repository
• Repository sync documentation