Splitting a monorepo into diagrams: by ref and by view, not by folder

A connection is the repository plus, for a private repo, its token, and diagrams hang off it one per branch or tag. A monorepo that ships continuously from main and cuts release tags therefore gets a living diagram on main plus a frozen one per release, from a single connection and a single token.

The long-lived branch is the second use of this split, and in a monorepo it is the more valuable one. When a migration is halfway done, main and the migration branch describe two different architectures, and a diagram on each turns the review into a comparison of pictures rather than a reading of diffs. The details of ref choice are in branch or tag.

On the first sync, Datadef reads the repository and then asks what the diagram should show, with a recommendation derived from the file counts it found. The two answers are different questions about the same code. The architecture view draws the system around it: what runs, where it runs, how it ships. The content view draws what the code does: the models, the schemas, the transformations, the flows.

The important part is that the answer reshapes the reading, not just the drawing. Under the architecture view the corpus can take up to sixteen infrastructure files and only three dbt models. Under the content view those numbers invert, up to eighteen models and only three infrastructure files. The reordering matters as much as the ceilings: the architecture view fetches infrastructure, containers, CI, and manifests before it looks at a model file, and the content view does the reverse. Two diagrams of the same monorepo are therefore built from two differently weighted samples of it, which is what stops each one from being a diluted version of both.

The ceilings are worth doing arithmetic on before you choose. On a monorepo dense in infrastructure, the architecture view can reach 16 .tf files, 14 deployment manifests and 8 Dockerfiles before it looks at a CI pipeline, which is 38 of the 40 slots. A repository like that never reaches its dependency manifests, and the services they describe arrive only as directory counts. If the manifests are what identify your services, the balanced default or the content view is the better pick, and the tree summary is what keeps the unread services visible either way.

Answering both at the ask creates the sibling diagram on the same ref, already committed to the other view, each with its own architecture.md. That is one connection, one branch, two pictures, and no canvas trying to be a deployment diagram and a data model at the same time.

Per-class ceilings, same repository, same branch

  class                architecture view   content view   default
  infrastructure (.tf)        16                3            12
  deployment manifests        14                3            12
  CI pipelines                10                2             8
  compose / Dockerfiles        8                2             6
  dbt models                   3               18            12
  other SQL                    3               14            10
  API specs (proto, OpenAPI)   4               12            10
  migrations                   2                8             6

  both views    40 files and 250KB in total, 30KB per file,
                plus a directory summary, 3 levels deep, 80 lines max

A connection reads the repository, not a subdirectory of it. There is no per-service or per-path scoping today, so a thirty-service monorepo produces a platform-level diagram rather than thirty service diagrams. Saying that plainly matters more than it sounds, because the alternative is discovering it after connecting.

For most teams the platform level is the artifact they wanted anyway. The questions people bring to a monorepo diagram are about the seams: which service owns that table, what sits between the API and the warehouse, where does this queue go. Those live above any single service.

One consequence to plan around: the directory summary that rides along with the corpus is capped at eighty lines. A monorepo with more than eighty directories in its top three levels has the rest of that listing cut, so the parts you care about are better placed shallow than buried four levels down under a tooling folder.

When one service really does need its own diagram, the agent path is the right instrument. Over MCP, a coding assistant reads the subtree you name on your own machine and drives the canvas directly, so draw the checkout service and everything it calls produces exactly that. It updates when you ask instead of daily, which is a fair trade for a picture that has a narrower subject.

• Repo to diagram: how repository sync works
• What a repo sync reads from your codebase
• Branch or tag: what your diagram tracks
• Draw diagrams with your AI agent over MCP
• Onboarding engineers to your architecture