Architecture as Code
September 18, 2025
Imagine a tool running quietly in the background. Nobody’s quite sure what it does, who built it, or why it still exists. It has no clear owner, no trusted documentation. Yet somehow, it serves around 250,000 clients every year. It works, so people leave it alone.
Until one day, it crashes.
Suddenly, this forgotten tool becomes urgent. The operations team scrambles to bring it back, but there’s nothing to go on. No README, no diagrams, no code comments. Just a PDF from 1999 called something like System Overview (Final_v3_new).docx.
We’ve all seen situations like this. Systems that are important, but are barely understood. No one really owns them, and no one keeps track. And when something goes wrong, everyone’s left guessing.
It’s a reminder: when architecture lives only in someone’s head, or in no one’s, it becomes a risk.
The answer isn’t to go back to the old “ivory tower” way of working, where one architect makes all the decisions alone and writes everything down in a big document. That doesn’t help the team, and it doesn’t scale.
Instead, we need a practical approach. One where architecture is part of everyday work. Shared by the team. Visible in the code. Easy to find and easy to update.
This article spotlights three building blocks that support that way of working:
- Diagrams that explain the system on different levels
- Documentation that shows why key decisions were made
- Fitness functions that check if the architecture remains compliant with the rules
Each of these should be supported by easy-to-use tools. In this article we take a look at the C4 Model for diagrams, ADRs for decision making, and ArchUnit to test architectural rules in code.
This approach makes architecture a team effort. Everyone can understand it. Everyone can help keep it healthy. And we’re less likely to be caught off guard by systems no one remembers.