Architecture as Code, Part 1: What It Is

I have spent a lot of my working life looking for the current version of an architecture diagram. Not a diagram. The diagram. The one that is actually true today.

You know the drill. There is a slide deck from a workshop, a wiki page someone started and abandoned, a drawing tool export in a shared folder, and a diagram embedded in a solution document that was correct at the moment it was written and has been quietly rotting ever since. All four disagree. Nobody can tell you which one wins, because none of them ever claimed to.

This post is about the way out of that, and about how we have built it in practice. First the short version of the idea, then the actual setup, then the parts that bit us.

Part 1: What architecture as code means

The idea is simple enough to fit in one sentence: treat your architecture description like source code.

That means it lives in a Git repository. It is written as plain text. It is reviewed in pull requests. It has a structure that a machine can validate. It gets built and published by a pipeline, the same way an application gets built and deployed.

The useful metaphor here is the difference between a photograph of a house and the blueprints of a house. A photograph is what most architecture documentation is. It is a snapshot from one angle, taken on one day, for one audience. It is not wrong exactly, it is just frozen, and you cannot renovate from it.

Blueprints are different. They are structured, they have a legend, they use agreed symbols, and critically they are the thing the builders actually work from. When the building changes, the blueprints change, because otherwise the next contractor breaks something.

Architecture as code is the attempt to make architecture documentation behave like blueprints instead of photographs. Concretely you get four things you did not have before:

1. History. You can see who changed what, when, and why. A diff on an architecture decision is a surprisingly powerful artifact.
2. Review. A change to the landscape arrives as a pull request. People argue about the content, in writing, before it is merged, rather than six months later in a meeting.
3. Derivation. If a fact is stored in exactly one place, every other view of that fact can be generated. Diagrams stop drifting because nobody draws them by hand.
4. Machine readability. This mattered less five years ago. It matters enormously now that we want AI agents to help maintain and query the landscape. An agent cannot reason about a picture of a box. It can reason very well about a table with stable identifiers.

That last point is the one that changed my mind about the whole approach. We started doing this for the humans. We kept doing it because it turned out to be the only format the machines could help with.

Stay tuned for Part 2: How we do it.