The Architecture Belongs in the Repo

Somewhere there is a diagram of your system. It is probably in a slide deck, it was probably last accurate eighteen months ago, and the architecture it describes drifted from the running system so slowly that nobody can name the moment they diverged. A decision got made in a meeting, a service got split, a queue got added, and none of it made it back to the picture. The picture and the system are now two different things, and only one of them is real.

That drift is the same failure the infrastructure post opened with, one layer up. Infrastructure fixed it by putting the desired state in git and letting a reconciler enforce it. Architecture can have the same thing, and this is where the series turns from infrastructure to the first genuinely soft artifact: the meaning of the system, not just its running config. This is the semantic layer, and architecture is its first domino.

The five artifacts worth versioning

You do not need a heavyweight enterprise-architecture practice to start. I argued in Architecture Without Architects that you get most of the alignment from five artifacts, and the point that matters here is that all five are text, and text goes in git.

Architecture decision records, so the why of each choice is captured at the moment it is made instead of reconstructed later. A C4 model of context, containers, and components, authored as text rather than drawn by hand. An application catalog. A tech radar of what is adopt, trial, or hold. And lightweight service contracts. None of those is a diagram trapped in a deck. Each is a file, and a file has a history, a diff, and an owner.

The move is the same one the whole series keeps making. Take the artifact out of the document graveyard, where it rots quietly, and put it somewhere it can be versioned, reviewed, and enforced. For architecture that somewhere is the repository, next to the code the architecture is supposedly about.

Governance lives in the diff

Once the model is text in git, something changes about governance that is easy to miss. The review stops being an event and becomes a diff.

I made the core of this case in Architecture Is the Prompt: the model in the repo is a queryable corpus, compliance metadata rides along as tags, and one corpus serves both an agent that needs context and an auditor who needs evidence. I will not re-argue that here. What this post adds is the lifecycle around it. A corpus that just sits there is documentation. A corpus that every change has to pass through is governance.

Picture an architect proposing a new integration. Instead of a slide, the proposal is a commit: a new ADR, an edited container in the C4 model, a contract file. A reviewer sees exactly what changed, in the same tool they review code in. The examiner, months later, does not ask anyone to reconstruct the decision, because the decision is a commit with a date, an author, and the discussion attached. Governance stopped being a meeting on a calendar and became a pull request in a queue.

What build, test, and gate mean for architecture

The infrastructure post named a loop: source of truth, change, test, gate, promote. Here is what each stage becomes when the artifact is architecture rather than a cluster.

Build is rendering. You author the model as text and generate the diagrams from it, the way tools like Structurizr render a C4 model, so the picture is always a build output and never a thing someone forgot to update. The diagram cannot drift from the model because it is produced from the model.

Test is conformance. Some of it is genuinely automatable: does this ADR adopt something the tech radar marks as hold, does this contract change break a declared consumer, does a container reference a data store it is not allowed to touch. Those are checks that can fail a pull request before a human spends attention on it. Gate is the review that a human still runs on the parts a check cannot judge. And promote is publishing the agreed reference architecture, versioned, so “the current architecture” is a tag and not a rumor.

The entity model is the floor

If you want the single most load-bearing piece of the semantic layer to version first, it is the data model. I argued in An ERD Is the Floor, Not the Ceiling that the entity model is the minimum shared, versionable definition of what the business is even talking about, and that a query result or a view is not a substitute for a design.

That matters doubly here, because the semantic layer is what grounds an agent. An architecture corpus with a vague or absent data model is a corpus an agent will happily misread. Versioning the entities, their relationships, and the words the business uses for them is not a nice-to-have adjacent to architecture-as-code. It is the part everything else hangs from, and the documentation becomes the source that both humans and models read.

What the diff can’t decide

The honest limit, the same shape as every post in this series. Putting architecture in the repo makes the mechanical half enforceable: drift, broken contracts, radar violations, missing decisions. It does not make the interesting half automatable. Whether a design is the right design, whether splitting this service is wise, whether this coupling will hurt in two years, none of that has a test that goes green. That judgment stays human, and it should.

What the repository buys is not automated architecture. It is that the human judgment now happens against a source of truth that is current, diffable, and shared, instead of against a slide from last year that no longer matches the system. The reviewer argues about the decision that matters instead of first spending an hour figuring out what actually changed. That is the whole gain, and it is enough.

So stop reviewing architecture once a year in a room. Put the model where the code is, let the build render the picture, let the checks catch the mechanical violations, and spend the human review on the questions only a human can answer. The infrastructure world proved the loop works. Architecture is just the next artifact to walk through it.

---

If this resonated, read Architecture Is the Prompt, on the architecture corpus as queryable context, and The Domino That Already Fell, on the infrastructure loop this post generalizes. Both sit in the Everything as Code series, alongside the pillar.

Find me on X @orestesgarcia or LinkedIn /in/setsero.