A single source of truth for architecture: the code is the truth, diagrams are projections

The model that makes the rule concrete has three layers. The source layer is whatever deployment reads: application code, IaC, database schemas, pipeline definitions. It is authoritative by construction, not by declaration, because when it changes, production changes. Nothing else in the organization has that property.

The projection layer is the human-readable compression of source: an architecture diagram, a schema doc, a dependency graph. A projection is legitimate exactly to the degree it is generated, because a generated projection can be re-derived at any time and checked against source, while a hand-drawn one can only be believed. The copy layer is what readers actually see: the diagram on the wiki page, in the README, in the onboarding doc. Copies are where drift historically enters, because every pasted export is a fork that starts aging at paste time.

Locate any dispute about what is true in this model and it resolves itself: source outranks projection, projection outranks copy, and a disagreement between two layers means the lower one regenerates. Documentation drift is what accumulates whenever a layer is maintained by hand instead.

The copy layer has a mechanical fix: embed by URL instead of pasting files. When every surface points at the same URL, there is one artifact with many windows onto it, and the concept of an out-of-date copy stops existing. Edit the diagram once and every README, wiki page, and doc site showing it follows; Datadef serves the embed image with a five minute cache lifetime and an ETag keyed to the last edit, so the copies converge within minutes rather than instantly, which is honest and sufficient for documentation.

The same artifact takes two URL forms because platforms differ: an image endpoint for surfaces that render images, which is the right form for GitHub READMEs since GitHub strips iframes, and an interactive page for surfaces that allow iframes, where readers can pan and zoom. The platform-by-platform details live in embed diagrams in Markdown. One boundary to concede up front: embed URLs exist only for projects shared public, so a confidential architecture keeps its copies as disciplined exports and accepts the drift risk that reintroduces.

One projection, embedded by URL everywhere. Edit once; every copy follows.

GitHub README (images only, iframes are stripped):
![Platform architecture](https://datadef.io/api/embed/platform-a1b2c3d4)

Notion or Confluence (iframe embed, readers pan and zoom):
https://datadef.io/embed/platform-a1b2c3d4

Docs site, sized for a wide layout:
<img src="https://datadef.io/api/embed/platform-a1b2c3d4?width=2400&scale=2"
     alt="Platform architecture" />

Embedding solves the copy layer completely, which moves all remaining discipline to one place: the edge between source and projection. Someone or something must regenerate the projection when the source changes, and being precise about the mechanics matters. Datadef does not watch repositories and does not auto-detect changes. What it provides is an MCP server, registry name io.datadef/mcp, so an agent such as Claude Code or Cursor connected to it can read the repository and update the diagram in one command: after a merge, in a path-filtered CI job, or on request during review. API access for that connection is available on paid plans.

This concentration is the practical win of the three-layer model. Instead of policing every page that shows the architecture, you maintain one regeneration loop, and keeping architecture docs in sync with code covers wiring it. A projection with a broken loop rots like anything else; the difference is that one loop is auditable and fifty wiki pages are not.

The model also arbitrates the harder fight, two artifacts each claiming to be authoritative. The test is always the same question: which one does deployment read? If infrastructure is changed in the cloud console while Terraform files sit in the repo, the live environment is your de facto source and the Terraform is fiction; the fix is not better documentation but importing the drift back into code, because a projection generated from fictional source is fiction with better formatting.

When a hand-maintained wiki page and a generated diagram disagree, the generated artifact wins by construction and the page loses its claim: delete its architectural content and replace it with the embed. And when two hand-maintained documents disagree, the honest answer is that you have zero sources of truth, not two; pick the layer-one artifact both should derive from, generate one projection, and demote both documents to copies. This is living documentation stated as a governance rule rather than a workflow.

• Living documentation
• Documentation drift
• Keep architecture docs in sync with code
• Embed diagrams in Markdown
• Terraform infrastructure diagram