Generate architecture.md from a repository: one read, two artifacts

Two separate failures wear the same name. The first is the blank page: an architecture overview is the document that pays back the least at the exact moment somebody has to write it, because the author already knows the system. The second is silent decay. Prose has no type checker. A component removed in March leaves its paragraph behind, and the paragraph reads exactly as confidently as it did when it was true.

Both failures share a cause. The doc is a hand transcription of information that already exists somewhere machine-readable: Dockerfiles, compose files, Kubernetes manifests, IaC, CI workflows, package manifests. Transcription by hand is expensive once and wrong forever after.

The section set is fixed rather than improvised, which is what makes two docs from two repositories comparable. The default shape is an overview, a component inventory with a one-line role each, the data flow through the system, how it builds and deploys, and short notes per notable directory.

At the first sync Datadef asks one question: should this repository be documented as the system around the code, or as what the code does. The architecture answer produces components, infrastructure, build and deployment, and directory notes. The content answer produces data models, data flow, logic notes, and directory notes instead. The proposal is composed from the file counts in the repository, so a repo full of Terraform and a repo full of dbt models get different suggestions without a model guessing.

The directory notes section is the one readers use most and the one nobody writes by hand. It is a short line per notable directory saying what lives there, which is precisely the map a person needs before their first pull request.

architecture focus          content focus            terraform repository
-------------------------   ----------------------   --------------------------
# Architecture              # Overview               # Architecture
## Diagram                  ## Diagram               ## Diagram
## Components               ## Data models           ## Stacks and environments
## Infrastructure           ## Data flow             ## What gets provisioned
## Build and deployment     ## Logic notes           ## How it wires together
## Directory notes          ## Directory notes       ## Operations
                                                     ## Module reference

The whole repository does not fit in a prompt and does not need to. Selection walks the tree once and takes files in priority order: infrastructure as code first, then containers and orchestration, then data (dbt projects, SQL DDL, Prisma schemas, sampled migrations), then API specs, then CI workflows, then package manifests, then README and docs prose. It stops at 40 files or 250KB, whichever comes first, truncating anything over 30KB with a visible marker.

Per-class ceilings stop one noisy category from crowding out the rest, and they move with the focus. Under the architecture focus the read allows 16 infrastructure files, 14 Kubernetes manifests, 10 CI workflows, and 3 dbt models; under the content focus that inverts to 18 dbt models, 14 SQL files, 12 API definitions, and 3 infrastructure files. A repository holding two hundred models cannot push the Dockerfiles out of the budget either way. Migrations are the one class sampled from both ends, half from the oldest and half from the newest, because the first files show the initial schema and the last show the current direction of change.

A compact summary of the top three directory levels rides along, so the writer sees the shape of what was not included rather than assuming the selection was the whole repository. Lockfiles, binaries, and directories like node_modules, vendor, .terraform, and dist are never candidates at all.

The writing rules are strict about invention. Every statement has to be grounded in the provided files, nothing may be invented that the files do not show, and a section the files do not answer gets one line saying so rather than a plausible paragraph. The practical consequence is worth stating plainly: architecture that lives nowhere in the repository will not appear in the doc.

One section of the generated doc is composed in code rather than written by the model, and it is inserted at a fixed position: immediately after the overview, before the first model-written heading, so a reader sees the shape before the prose. A model asked to produce an embed URL will invent a slug that resolves to nothing, which is the failure this removes. The URL is either real or replaced by the instruction for making it real.

From the Canvas tab of the right-hand panel you can copy or download the markdown, so committing the file next to the code is a two-step operation. The diagram itself exports as PNG or JPEG when someone needs a still image for a slide.

That section is also rebuilt on every sync, including the ones that skip regeneration because the structure has not moved. Switching a project to link sharing puts the real embed line into the document on the next pass without touching a single model-written sentence, and switching it back replaces the line with the instruction again. Both states look like this.

<!-- project shared by link: the URL is real -->
## Diagram

![Acme platform](https://datadef.io/api/embed/acme-platform-4f2c)

This image stays current with the canvas: every sync renders the latest diagram.

<!-- project not shared: no invented URL, just the way to get one -->
## Diagram

To embed the live diagram here, open the project in Datadef, click Embed,
switch on Anyone with the link, and the markdown line to paste will be there.

• Repo to diagram: how repository sync works
• Keep architecture docs in sync with code
• Terraform documentation generator
• Living documentation
• Repository sync documentation