Architecture documents stop being true the moment the system they describe ships. That's the problem. The diagram on the wiki is wrong by next sprint. The decision record was accurate when it was written, but is silently incorrect by the time someone needs to act on it. The slide deck shipped to executives describes a system that no longer exists. Architecture as Code exists because that pattern is too expensive to keep paying for.

This guide is the 2026 primer. It covers what Architecture as Code actually is (and what it's not), the case for treating architecture the way teams already treat infrastructure, the distinction between Architecture as Code and Infrastructure as Code, how the practice works in production, the frameworks and tools that have emerged, the fitness-function piece most teams skip, and where the category is going as AI agents start to participate in the loop. It's written for software architects, platform leads, and engineering managers who want their architecture artifacts to stay honest for longer than a quarter.

What Is Architecture as Code?

Architecture as Code is the practice of defining, validating, and evolving software architecture using machine-readable, version-controlled artifacts. The shape mirrors the discipline teams already apply to application code and infrastructure: the source of truth is text in a repository, changes go through review, and automation can verify that what's running matches what was committed. It is the natural endpoint of treating architecture as a living system instead of a slide deck.

A few clarifications first.

• It's not just diagrams in a Git repo. A PNG in version control is still a PNG. Architecture as Code means the model behind the diagram is itself machine-readable, validatable, and capable of generating multiple views (or none, when the team prefers code-level abstractions).
• It's not the same as Infrastructure as Code, but it's adjacent. IaC defines the cloud resources that get provisioned. Architecture as Code defines the system that the resources are supposed to compose, including the parts that IaC doesn't touch (teams, contracts, processes).
• It's not a fully solved category in 2026. The vocabulary has settled. The tooling is converging. But the practice is still emerging, and most teams are doing it partially rather than completely.

The closest mature analog is what happened to documentation. Wikis used to be the default; engineering organizations gradually learned that documentation living in the same repository as the code, written in the same review workflow, with the same automation, stayed honest in ways the wiki never did. Architecture as Code applies the same lesson one layer up.

The Case for Architecture as Code

There are three pieces to the case.

The first piece is staleness. Architecture artifacts that don't share a workflow with the code they describe go stale within months, with diagrams drifting, decision records being silently superseded, and slide decks shipping and being forgotten. Code-based artifacts inherit the team's existing review discipline, which helps keep application code and infrastructure roughly current.

The second is continuous validation. Once architecture lives as code, it can be validated against the running system the same way tests validate behavior. Did the team commit to "all services authenticate through the identity broker"? A validation check can ask whether any service in production is bypassing it. Did the architecture say "no service depends on more than three downstream services"? A check can flag the one that now depends on four. The validation isn't a one-time audit; it's continuous.

The third is fitness functions. The concept comes from Neal Ford, Rebecca Parsons, and Patrick Kua's Building Evolutionary Architectures (O'Reilly, 2017; second edition, 2023, with Pramod Sadalage). An architecture can be characterized by a set of measurable properties (latency budgets, dependency depth, coupling metrics, security boundaries), and a fitness function is the executable check that those properties still hold. Fitness functions are how a code-defined architecture stays honest under continuous change.

Together, those three are the case. None is novel on its own. What's new is that the tooling has matured enough to make the practice realistic.

Architecture as Code vs. Infrastructure as Code

The two terms get conflated. They sit at adjacent layers and solve different problems.

Both treat their domain as version-controlled artifacts. Both inherit the team's existing review and CI workflow. The boundary is whether the artifact is about what gets provisioned (IaC) or what the system is supposed to be (AaC). A team that uses Terraform to provision an EC2 instance is doing IaC. A team that uses CALM to assert "the customer-facing services live in the public subnet, the data services live in the private subnet, and the boundary between them is enforced" is doing AaC. Both can be true at once, and usually are.

How Architecture as Code Works

The mechanics are familiar to anyone who has used Infrastructure as Code or treated documentation as code.

Modeling the System

The first step is modeling the system in a machine-readable format. Several conventions exist, including:

• CALM (the FINOS Common Architecture Language Model) uses JSON Schema
• Architecture-as-Code (AaC) uses YAML
• Structurizr's DSL is custom
• Sometimes teams write their own DSLs in Python or TypeScript. 

The choice matters less than the discipline of keeping the model up to date.

Versioning and Review

The model lives in a repository. Changes go through pull requests. Reviewers see the diff the same way they review code or IaC changes. The architecture review process inherits the engineering review process, which is the biggest practical benefit and the largest cultural shift.

Validation Against the Running System

The model is one half of the story; the running system is the other. The most powerful Architecture-as-Code implementations close the loop by comparing the model against the system's live state. The architecture says "service A depends on service B and only service B." The validator checks the production dependency graph and flags whether reality matches. This is the system architecture closing the loop in the most literal sense.

Generating Views, Diagrams, and Docs

Once the model exists, the views are derivable: C4 diagrams, dependency graphs, sequence diagrams, and deployment views. The team writes the model once and gets the views for free, which is the inverse of the traditional pattern where every view was hand-maintained. For a broader treatment of architecture diagrams (and what makes one useful), see our "art and science of architecture diagrams" post.

Architecture as Code Frameworks and Standards

The category has settled around a handful of recognized frameworks.

FINOS CALM (Common Architecture Language Model)

CALM is one of the most visible emerging open standards in the category. It's a JSON-Schema-based language for describing architectures in a vendor-neutral way, hosted by FINOS (the Fintech Open Source Foundation). Adoption is still concentrated in financial services, where the discipline of formal architecture description is most acute. The standard is worth tracking even if your team isn't ready to commit; the vocabulary is converging on it.

arch-as-code.org (AaC)

A different and earlier project, with a YAML-based DSL and a focus on model-based systems engineering practices. AaC has less commercial traction than CALM but a more formal methodological foundation.

C4 Model + Structurizr

Simon Brown's C4 model (Context, Container, Component, Code) is the most adopted diagramming convention for software architecture, and Structurizr is its tooling ecosystem. Strictly speaking, C4 is a diagram model rather than a full Architecture as Code framework, but Structurizr's DSL has Architecture-as-Code properties: text definitions, version control, and generated views. Many teams that say "we do AaC" mean Structurizr.

PlantUML + Custom Validators

The pragmatic lower bound. PlantUML for the diagrams, custom scripts (often in Python) for the validators that check the model against the running system. Less elegant than CALM or Structurizr, but cheaper to start and easier to evolve toward something more formal.

Architecture as Code Tools (2026)

The tooling splits roughly into three categories.

Modeling and diagram tools. Structurizr, Likec4, IcePanel, and the diagrams-as-code ecosystem (PlantUML, Mermaid). Useful for teams that want the diagram-and-model side without committing to a full framework.

Validation and fitness-function tools. ArchUnit and similar tools enforce structural constraints in code (typically at build time). The broader fitness-function discipline isn't a tool category yet; it's a practice that uses general-purpose testing infrastructure.

Architecture decisions and live system observability. This is where Catio sits, alongside a small set of peers in the category. The category treats architecture as code plus the running system, with the decisions tied to live state, so the model can be validated continuously, and the team can detect when the system has drifted from the architecture it was committed to. For the broader landscape of architecture-level tooling, see our roundup of software architecture tools.

Fitness Functions: The Missing Piece

Architectural fitness functions, the framing introduced in Building Evolutionary Architectures and refined in Neal Ford and Mark Richards' Fundamentals of Software Architecture, are part of Architecture as Code that most teams haven't operationalized yet. The idea is that an architecture can be characterized by measurable properties, and a fitness function is the executable check that those properties still hold.

A worked example might look like this: The architecture says "the order service must respond at p95 < 200ms under normal load." A fitness function is the continuous benchmark that asserts this against the production system. The architecture says "no component depends on more than three downstream services." A fitness function is the dependency-graph check that flags violations. The architecture says "all production secrets are managed through the secrets layer, never inline." A fitness function is the static analysis that catches inline secrets in PR review.

Fitness functions are where Architecture as Code stops being a documentation discipline and starts being an enforcement discipline. They're also where most adoptions plateau, because the team needs to write the fitness functions, which is real engineering work. The teams that get past the plateau are the ones that treat fitness functions as part of the architecture itself, not as a separate testing investment.

When Architecture as Code Makes Sense (and When It Doesn't)

The practice pays off in a specific organizational shape.

• Team size: Roughly 20+ engineers. Below that, the overhead of maintaining the model exceeds the staleness cost that the practice prevents.
• Architecture cadence: Active architecture work, with new services or changing boundaries on a regular cadence. Stable systems don't benefit much; the architecture doesn't change often enough to need continuous validation.
• Compliance and regulated industries: Healthcare, fintech, defense. The discipline of formal architecture description maps directly onto audit requirements.
• Multi-team organizations: When several teams share an architecture, the cost of keeping everyone aligned on a stale wiki page is high, and the value of a code-defined model is correspondingly large.

It doesn't pay off when the team is small enough that the architecture lives in one person's head and stays there, when the system is mature and stable enough that staleness isn't a real cost, or when the engineering organization doesn't have the discipline to maintain the model (in which case Architecture as Code becomes another wiki page in a different format).

The Future of Architecture as Code

The shape the category is moving toward is roughly the one we’ve built Catio around: architectural decisions captured as code-like artifacts, tied to the live state of the system, with AI agents able to read, reason about, and even propose changes to the corpus. The static DSL approaches (CALM, AaC) remain useful as the formal description layer; what's emerging on top of them is the decision and validation layers that operate continuously.

A few specific things are changing.

The first is that architectural decisions are being treated as first-class artifacts at the same layer as the architecture model, rather than as documents written separately. The connection to architecture decision records is direct: ADRs are the artifact, Architecture as Code is the substrate, and the live system is what both must remain consistent with.

The second is that AI agents are starting to participate in the loop. An agent that can read the architecture model, the decision corpus, and the live system state can answer questions like "which decision did this drift event invalidate?" or "which fitness function would flag the change this PR is making?" in ways no static document workflow could.

The third is that the line between architecture and the rest of the engineering organization's tooling is blurring. The enterprise architecture tools category, the platform engineering stack, and the observability layer: each touches the architecture description in different ways. The category emerging on top is the one that treats the description as a substrate on which the rest of the tooling can compose.

Closing the Loop

Architecture as Code is the practice that turns architecture from a snapshot the team produces occasionally into a substrate the team works on continuously. The vocabulary has settled, the frameworks exist, and the tooling is converging. What's still emerging is the layer above: decision systems that treat the architecture model and the running system as a single, continuous system.

If your team is at the point where architecture artifacts are starting to stay current for longer than the wiki ever did, and you want the next layer (decisions tied to live state, validated continuously, accessible to AI agents that can reason across the corpus), see how Catio approaches architecture as a system of decisions rather than as a directory of files.

Frequently Asked Questions

What is the difference between architecture as code and infrastructure as code?

Infrastructure as Code defines the cloud resources that get provisioned (instances, networks, identity). Architecture as Code defines the system that those resources are supposed to compose into (services, contracts, decisions, fitness functions). They're adjacent and complementary; most teams that do one well also benefit from doing the other.

Is architecture as code the same as the C4 model?

No. C4 is a diagramming convention with four levels (Context, Container, Component, Code). Architecture as Code is the broader practice of treating architecture artifacts as machine-readable, version-controlled, and validatable. Structurizr (the C4 tooling ecosystem) has Architecture as Code properties, but the C4 model itself is one piece of the broader practice.

What languages do architecture-as-code tools use?

The major options use different shapes. CALM is JSON Schema, AaC is YAML, Structurizr has a custom DSL, and PlantUML uses its own text format. Custom DSLs in Python or TypeScript show up in teams that want full programmatic control. There's no single standard yet, and the choice matters less than the discipline of maintaining the model.

Do I need a dedicated architect to use architecture as code?

No, but you need someone (or a small group) accountable for maintaining the model. In smaller organizations, this is usually a staff engineer or tech lead; in larger ones, it's a dedicated architecture team. The role matters more than the title; what doesn't work is treating the model as everyone's responsibility and therefore no one's.

‍