paulserban.eu

Writing Edition

Paul Serban

Writing, snippets & book notes

Vol. 2026

February 09, 2023

Architecture as Code: What It Is, Why It Matters, and How to Implement It

A practical guide to codifying architectural decisions, enforcing them automatically, and keeping documentation synchronized with the systems it describes

Introduction

Every non-trivial software system accumulates architectural decisions faster than anyone can document them by hand. A team chooses a message broker, sets a rule that services never talk directly to another team's database, decides that a particular module must remain framework-agnostic - and within a few sprints, half of that context lives only in Slack threads, meeting notes, or the memory of whoever was in the room. The diagram on the wiki, carefully drawn eighteen months ago, no longer resembles the system running in production. This gap between the architecture people believe exists and the architecture that actually exists is one of the most persistent and expensive problems in software engineering.

Architecture as Code (AaC) is a response to that problem. Instead of treating architecture as a set of documents maintained separately from the codebase, AaC treats architectural decisions, constraints, and structural diagrams as versioned artifacts that live alongside application code, get reviewed the same way, and - critically - can be checked automatically. This article explains what Architecture as Code actually means in practice, why the discipline has become increasingly relevant as systems scale into distributed, multi-team environments, and how engineering teams can adopt it incrementally without turning architecture governance into bureaucratic overhead.

The Problem: Why Traditional Architecture Documentation Fails

Architecture documentation has historically taken the form of static artifacts: PowerPoint slides, Visio diagrams, Confluence pages, or PDF design documents produced during an initial design phase. These artifacts capture a snapshot of intent at a single point in time. The problem is that software systems are not static - they evolve continuously through hundreds of small pull requests, each of which can quietly violate an architectural principle nobody remembers to check. A diagram that took a day to produce can become inaccurate within a week, and once it is inaccurate, engineers stop trusting it, which means they stop consulting it, which means the documentation effort was largely wasted.

A second failure mode is that architectural decisions are frequently made verbally, in design reviews or hallway conversations, without any durable record of the reasoning behind them. Six months later, a new engineer asks "why don't we use a shared library for this?" and nobody can produce a clear answer, because the decision was never written down - only the outcome persisted, stripped of its context. This creates a form of institutional memory loss that is particularly damaging during team turnover or organizational restructuring, when the people who understood the trade-offs are no longer available to explain them.

A third, more structural failure mode is governance friction. When architectural rules exist only as guidance in someone's head or in a document nobody reads, enforcing them requires manual review - an architect or senior engineer manually inspecting pull requests for violations. This does not scale past a handful of teams, creates a bottleneck around a small number of reviewers, and turns architecture into a gatekeeping function rather than a shared engineering practice. Architecture as Code directly targets all three failure modes by making architecture a first-class, machine-checkable part of the codebase rather than a parallel, informally maintained artifact.

What Is Architecture as Code

At its core, Architecture as Code is the practice of expressing architectural structure, constraints, and decisions in a form that is text-based, version-controlled, and - wherever possible - automatically verifiable against the real system. This includes writing architecture decision records (ADRs) as markdown files committed to the repository, describing system structure using diagram-as-code tools such as the C4 model or Structurizr's DSL rather than freeform drawing tools, and defining dependency or layering rules as executable tests that run in continuous integration. The unifying idea is that architecture should be treated with the same engineering rigor as application logic: reviewed in pull requests, subject to version history, and enforced by tooling rather than by memory or goodwill.

It is worth distinguishing Architecture as Code from the closely related and often conflated concept of Infrastructure as Code (IaC). IaC, using tools like Terraform, Pulumi, or AWS CDK, codifies the provisioning of infrastructure resources - networks, compute instances, databases. Architecture as Code operates one level up: it codifies the structural rules and decisions that govern how software is designed and how components are allowed to relate to one another, independent of what infrastructure it eventually runs on. Neal Ford, Rebecca Parsons, and Patrick Kua's concept of "fitness functions" from Building Evolutionary Architectures is a useful anchor here - a fitness function is any mechanism that provides an objective, automated assessment of whether a system still exhibits a desired architectural characteristic, such as modularity, performance under load, or security posture. Architecture as Code is, in large part, the practice of writing fitness functions and other structural checks as code.

Implementing Architecture as Code: Tools and Techniques

The most accessible entry point into Architecture as Code is the Architecture Decision Record. Popularized by Michael Nygard in a widely referenced 2011 post, an ADR is a short markdown document capturing a single architectural decision: the context that motivated it, the decision itself, and its consequences. ADRs are stored in the repository, typically under a directory such as docs/adr/, numbered sequentially, and never edited after acceptance - if a decision is reversed, a new ADR supersedes the old one, preserving the historical reasoning rather than erasing it. Tools like adr-tools and log4brains automate the creation and indexing of these records, but the format is simple enough that many teams maintain it with nothing more than a markdown template and a pull request review process.

A second technique is describing system structure using an architecture description language rather than a freeform diagramming tool. The C4 model, created by Simon Brown, defines a small set of abstraction levels - Context, Containers, Components, and Code - and Structurizr provides a text-based DSL for expressing C4 diagrams as version-controlled source files that render automatically. Because the diagram source is text, it can be diffed in pull requests, reviewed alongside the code changes that motivated it, and regenerated on every commit rather than manually redrawn.

The third and most powerful technique is encoding structural constraints as executable tests - the fitness functions mentioned earlier. In the TypeScript and JavaScript ecosystem, dependency-cruiser allows teams to define rules such as "the domain layer must never import from the infrastructure layer" as a configuration file that runs in CI and fails the build on violation:

// .dependency-cruiser.js
module.exports = {
  forbidden: [
    {
      name: "domain-cannot-import-infrastructure",
      comment:
        "Domain logic must remain independent of infrastructure concerns " +
        "such as databases, HTTP clients, or message queues.",
      severity: "error",
      from: { path: "^src/domain" },
      to: { path: "^src/infrastructure" }
    },
    {
      name: "no-circular-dependencies",
      severity: "error",
      from: {},
      to: { circular: true }
    }
  ],
  options: {
    doNotFollow: { path: "node_modules" },
    tsPreCompilationDeps: true
  }
};

In the Python ecosystem, import-linter provides an equivalent mechanism through a .importlinter configuration file defining "contracts" that describe permitted module dependencies, which can then be run as part of a standard test suite:

# .importlinter
[importlinter]
root_package = myapp

[importlinter:contract:1]
name = Layered architecture
type = layers
layers =
    myapp.api
    myapp.services
    myapp.domain
    myapp.infrastructure

# test_architecture.py
import subprocess

def test_architecture_contracts_are_respected():
    result = subprocess.run(
        ["lint-imports"],
        capture_output=True,
        text=True,
    )
    assert result.returncode == 0, result.stdout

Finally, policy-as-code tools such as Open Policy Agent (OPA), used through its conftest wrapper, allow architectural and compliance rules to be expressed declaratively in Rego and evaluated against configuration files, infrastructure manifests, or even API contracts - extending Architecture as Code beyond source-level dependency rules into deployment and platform governance.

Trade-offs and Common Pitfalls

Architecture as Code is not free. Writing fitness functions, maintaining diagram-as-code pipelines, and keeping ADRs current all require ongoing engineering effort, and that effort competes directly with feature delivery. Teams that adopt AaC enthusiastically but underestimate this cost often end up with an elaborate rule set that nobody maintains after the initial rollout, at which point the automated checks either go stale and get ignored, or worse, start blocking legitimate work because the rules never anticipated a new but valid pattern. The discipline works best when a small number of high-value rules are enforced rigorously, rather than when teams attempt to encode every architectural preference as a hard constraint from day one.

There is also a real risk of over-formalization slowing down teams that do not yet need this level of rigor. A five-person startup iterating on product-market fit gains little from a full ADR process and layered dependency contracts; the overhead of maintaining that machinery can outweigh the benefit when the architecture itself is still expected to change weekly. Architecture as Code delivers the most value in systems with multiple teams, long lifespans, or regulatory constraints where architectural drift carries genuine cost - and applying it uniformly regardless of context is itself an architectural mistake. A related pitfall is tool sprawl: combining diagram-as-code, multiple fitness-function frameworks, and policy engines without a clear owner or review cadence produces a maintenance burden that can rival the documentation rot the practice was meant to solve.

Best Practices for Adopting Architecture as Code

The most reliable path to adoption is starting small and specific rather than attempting a comprehensive rollout. Pick the one or two architectural violations that have caused the most real pain - a layering violation that keeps recurring, a circular dependency that periodically breaks the build - and encode only those as automated checks first. This gives the team an immediate, visible payoff and builds trust in the approach before extending it further. Teams that instead try to formalize their entire architecture on day one tend to produce rule sets that are either too strict to be practical or too vague to catch anything meaningful.

Once a few checks exist, they should run in continuous integration as blocking checks, not as advisory warnings that get routinely ignored. A fitness function that only produces a warning is, in practice, documentation that happens to be executable rather than a genuine architectural guardrail; a fitness function that fails the build is a guardrail. This distinction matters enormously for whether the practice actually changes engineering behavior or simply adds noise to CI output. Alongside this, ADRs should be reviewed with the same rigor as code - a lightweight template, a required reviewer from outside the immediate team for significant decisions, and a clear, searchable index - so the record remains a genuinely useful source of truth rather than a write-only archive.

Finally, ownership matters. Architecture as Code tends to decay in the same way traditional documentation does if no one is accountable for its upkeep. Assigning a rotating "architecture custodian" role, or making fitness-function maintenance an explicit part of a platform or architecture team's responsibilities, keeps the rules aligned with how the system actually evolves rather than freezing them around an early design that has since been superseded.

Mental Model: Architecture as Code Is a Compiler for Intent

A useful way to think about Architecture as Code is as a compiler that checks intent rather than syntax. A regular compiler catches type errors and syntax mistakes the moment they're introduced, long before a human reviewer would ever notice them by reading the diff. Architecture as Code applies the same principle one abstraction level higher: it catches violations of structural intent - a forbidden dependency, a bypassed layer, an undocumented decision - at commit time, rather than relying on a human architect to notice the same violation weeks later during a manual review, if they notice it at all.

This framing also clarifies where the discipline's limits lie. A compiler cannot tell you whether your algorithm solves the right business problem; it can only tell you whether the code is internally consistent with the rules of the language. Similarly, Architecture as Code cannot tell a team whether their chosen architecture is the right one for their product - that remains a judgment call requiring human experience and context. What it can do is guarantee that, once a structural decision has been made, the codebase stays consistent with that decision over time, freeing architects to spend their attention on judgment calls rather than on manually policing conformance.

The 80/20 of Architecture as Code

Not every technique described in this article delivers equal value, and teams with limited time should prioritize accordingly. In practice, a small handful of practices account for most of the benefit that Architecture as Code provides. Writing ADRs for genuinely significant decisions - not every decision, but the ones that would be expensive to reverse or confusing to future engineers - captures the majority of the "why did we do this" value at very low tooling cost, since it requires nothing more than a markdown file and a review habit.

The second highest-leverage practice is encoding two or three dependency or layering rules as automated fitness functions using something like dependency-cruiser or import-linter. These tools are simple to configure, run in seconds, and catch the specific class of violation - accidental coupling between layers that should remain independent - that causes the most long-term architectural erosion in real codebases. Diagram-as-code tools and policy engines like OPA add real value in larger, multi-team organizations, but they represent a smaller slice of the overall benefit and are reasonably deferred until the simpler practices are already in place and working.

The underlying pattern across all of these high-leverage practices is automation at the point of change. Rules that are checked automatically on every pull request compound in value over the life of a project, while rules that depend on a human remembering to check them decay predictably as the team grows and turns over. Prioritizing automatable, narrowly scoped constraints over broad, manually enforced guidelines is the single highest-leverage decision a team can make when adopting Architecture as Code.

Key Takeaways

Conclusion

Architecture as Code does not eliminate the need for skilled architects making sound judgment calls - no amount of tooling replaces the experience required to decide that a system should be modular in one dimension and monolithic in another. What it does is close the gap between the architecture a team believes it has and the architecture actually running in production, by making structural rules and decisions into versioned, reviewable, and - where possible - automatically enforced artifacts rather than fragile institutional memory.

Adopted incrementally, starting with a handful of ADRs and a small set of dependency rules checked in CI, the practice pays for itself quickly: fewer surprise violations discovered during incident reviews, fewer "why did we build it this way" conversations with no good answer, and documentation that developers actually trust because it is checked against reality rather than drawn once and forgotten. Like most engineering disciplines worth adopting, its value comes not from doing everything at once, but from doing the highest-leverage parts consistently and letting the practice grow only as far as the system genuinely needs it to.

References

A quick flashcard preview - one example of each question type in this post. This is a demo of what you'll find in the full quiz app.

Flashcard preview - 1 / 9Multiple Choice

multiple choice - intermediate - auto-graded

How does Infrastructure as Code (IaC) differ from Architecture as Code (AaC)?

Choose an answer