Generate the doc and the diagram from one read of the repository

When you connect a repository and pick a branch or tag, Datadef selects a bounded slice of the repository: up to 40 files and 250KB, chosen in priority order. Infrastructure as code first, then containers and orchestration, then data definitions such as dbt projects, SQL DDL and Prisma schemas, then API specs, then CI configuration, then package manifests, then prose. A compact summary of the directory tree goes with it: every directory to three levels deep with its file count, so the generation can see that src/services holds forty files even though none of them made the corpus.

Which slice you get is decided once, at the first sync, and decided without a model. The selector classifies every file in the tree and counts the two sides, the data side of dbt projects, SQL, Prisma schemas, migrations and API specs against the system side of infrastructure code, compose files, Dockerfiles, Kubernetes manifests and CI, then recommends the focus the larger side argues for and writes one deterministic sentence saying why. Phase one of a first sync therefore costs nothing in generation spend, and the recommendation is reproducible rather than a judgement call the model made that morning.

That same slice produces two outputs: the diagram, as a working canvas you can edit like any other, and an architecture doc in markdown. Neither is written from the other, and both are grounded only in the files that were read, so a service that appears nowhere in the repository appears in neither.

The single corpus is what makes them consistent. Two separately triggered generations read different files at different moments and reach different conclusions, and the disagreement is invisible until a reader notices it in a meeting.

# what the first sync proposes, computed from file counts, no model call

Mostly infrastructure code and Kubernetes manifests (34 files)
with 6 data model and API files.
  recommended focus: architecture

# the ceilings that focus then applies to the 40-file budget
  iac 16 · k8s 14 · ci 10 · manifests 8 · dbt models 3 · sql 3 · api 4

The doc has an overview, a component inventory, the data flow, how the system deploys, and notes per notable directory. Those are the parts that resist being drawn: a component inventory is a list, deployment is a sequence, and per-directory notes are the map a newcomer needs before the picture means anything.

The diagram carries what prose carries badly: how many things there are, what is inside what, and which paths exist. Reading them side by side is the point. A reader who wants the shape looks at the canvas, a reader who wants to know which directory to open reads the doc, and neither has to reconstruct the other.

Both live with the project. The repo link, the tracked branch or tag, the sync controls and the doc with copy and download sit in the Canvas tab of the right-hand panel, so the doc is one click from the picture rather than in a different tool.

A sync regenerates both. It first resolves the head commit of the tracked ref and stops there when nothing moved, then compares a structure fingerprint of what feeds the generation, so a commit that changed a README or a test does not redraw the diagram or rewrite the doc. What you get is a pair of artifacts that change when the architecture changes, and only then.

Daily sync runs about once a day per linked diagram while it is enabled, and a manual refresh is one click in the app or one repo_refresh call from an agent. Because both artifacts come from the same run, there is no state where one is a day newer than the other.

From an agent session the useful pattern is two calls: repo_status to get the commit the pair reflects, then repo_refresh if the branch has moved. Quoting that commit in a pull request description or a release note tells the reader exactly what version of reality they are looking at.

It is a map, not a decision log. Why the queue was chosen over direct calls, which trade-off was accepted, what was tried first: none of that is in the source, so none of it is in the doc. That material belongs in decision records written by people, and the generated doc is better for not attempting it.

It also carries no runtime truth. Which path actually serves traffic, what is deprecated but still live, which component is scheduled for deletion. A person adds those sentences, on the canvas as annotations or in a section of the page that the generation does not own.

Read that way, generated documentation covers the mechanical part nobody maintains by hand, and leaves the part that needs judgment clearly marked as human rather than quietly missing.

• Repo to diagram: the diagram and the doc
• Repository connections documentation
• ARCHITECTURE.md: what goes in it
• Keep architecture docs in sync with code
• Living documentation