Architecture as Code Needs a Standard, Not Only a Good Tool

For some years I tried to find a good method to keep architecture as code. I tested many tools. LikeC4 works well for me. I added it to fluxrig. The command fluxrig scenario viz reads a scenario file and writes a LikeC4 model. The diagram and the wiring use the same file, so they cannot disagree. The payment switch post shows the result.

LikeC4 solved the dead diagram problem for me. But LikeC4 is one vendor’s language. A model that only one tool reads is a dialect. A bank cannot build on a dialect. Architecture describes risk. An auditor must read the description. The next tool must read it too.

Recently I found CALM. CALM is the Common Architecture Language Model. It defines nodes, relationships, containers, controls, and flows in JSON Schema. Other tools validate the document, render it, and store it.

An earlier standard tried this. ArchiMate gives architects a common language, and its layers are clear. But a tool writes its files as XML, and a human finds them hard to write, review, or diff by hand. CALM gives a similar discipline and adds two things: readable JSON, and validation that runs in the build. The architecture as code blog entry records that verdict.

CALM did not start as a vendor product. A Morgan Stanley engineering team built it. Every application needs a diagram to pass security and compliance review, and that diagram drifts from the system it describes. Olivier Poupeney, field CTO at the Linux Foundation and FINOS, calls it out: “there is often a disconnect between what the diagram represents and the reality of the solution.” The team ran an architecture-as-code working group from 2023, and released CALM v1.0 through FINOS in August 2025. The framework now underpins thousands of deployments across several firms, and it shortened Morgan Stanley’s own review from months to weeks. CIO Dive told the story.

The project matters as much as the format. FINOS hosts it. FINOS is the Fintech Open Source Foundation, an umbrella body under the Linux Foundation. The regulated industry runs it, with more than 100 member organizations and over 50 open projects and standards. A vendor language answers to one company. A FINOS standard answers to the institutions that carry the risk. For a payment switch, that is the only kind of standard worth adopting.

This is not about the architecture alone. The ISO 8583 spec in two halves describes the other half. A protocol spec is data, not code. fluxrig keeps the message catalog, the valid values, and the per-message rules in the spec file. CALM keeps the architecture in a standard document. The two ideas agree. The description is the source of truth.

In fluxrig, a Rack is an edge node that processes the traffic, and the Mixer is the control plane.

The standard in action

The diagram below is not a picture. It is the CALM document of the two-region payment switch, rendered as SVG.

High-level view. Each region hosts a Rack. When a Rack has no local destination left for a request, it forwards the request to the Rack in the other region.

The documents are real and they validate. I ran calm validate (CALM CLI 1.60.1) on the overview and on both Rack details: 0 errors. Run it from the architectures/ directory. The CLI finds the Rack details relative to the current directory, and the repository README shows the commands. I changed one wire and calm diff reported the difference. The schema is the CALM 1.2 meta-schema, and the node types are a fluxrig: extension that the schema permits.

The generator is a script, not the running switch. It reads payment_switch_two_regions.yaml, the same kind of scenario file the Rack runs, and writes the CALM documents. Wiring CALM into the fluxrig binary is the next step. What exists today is the model, the validation, and the rendered diagram.

Two views drill below the overview:

rack-east: the gears, wires, and scheme uplinks inside one region.

rack-west: the mirrored region, reachable by failover.

The diagrams come from the Node render entry of the CALM Studio web component, run at build time. The output is static SVG, so the post carries no live service.

The model is public. Every document lives in fluxrig/calm-models on GitHub. The repository is the registry: each file is a versioned CALM document, and each version is the commit that changed it. LikeC4 already gave me this. A reader could open the model, diff two commits, and read the description without a proprietary tool. CALM keeps that property and standardizes it. The same file now carries a shared meaning across every tool that adopts the standard.

The Hub is the other half of the toolchain. It is a registry of architectures, patterns, and controls. A Hub in github storage mode reads the repository directly:

calm.database.mode=github
calm.github.namespaces=fluxrig|fluxrig/calm-models|main

The public Hub at hub.calm.finos.org is read-only and accepts no external namespaces. Any team can point its own Hub at this repository.

Views: the missing half

What I valued most in LikeC4 was the split between the model and the views. One model, and as many views as the reader needs: a deployment view for the platform team, a logical view for the developers, a focus view for the auditor. The model does not change; the view selects.

CALM separates the model from the presentation too, but not in the same place. It keeps the model pure, and it leaves the view to the tool that reads it. A CALM 1.2 document has no views property. The tool decides the focus: the CLI has focus-nodes, focus-flows, and focus-relationships options, and the Hub filters by node type. Those options live in the render call, not in the document. They are not named, not versioned, and not portable. A focus string in one tool does not transfer to the next.

This is a known gap, and it is under discussion:

• finos/architecture-as-code#2344, Add First-Class Views to CALM, is open. It proposes a views property in the document, with a name, an audience, and a filter over nodes, relationships, flows, and controls. It names the same problem: views are “ephemeral, not shareable, and not portable.” It cites Structurizr and the C4 model as the precedent.
• finos/architecture-as-code#2901 proposed a separate view document, with pins, direction, colors, and focus, next to the architecture. It is closed. The inline design of #2344 is the one that stands.

So today, in a two-region payment switch, rack-east and rack-west are not views of one model. They are separate documents that drill into each other. Each re-declares its own nodes. That is not the LikeC4 split, and I will adopt the view model once the standard carries it.

The part that CALM does support today is the decorator. A decorator attaches cross-cutting data to nodes in many documents at once, by unique-id, without touching the model. I moved the deployment facts there: the socket of every scheme, the Rack region, the gear placement and its wire settings. Nine nodes had their facts copied across documents. Now the facts live once in two decorators, and the node keeps only its identity and its presentation hint. A socket change is one edit in one file.

That is not a view. It is the other axis: not what to show, but what to say about a node that appears in many places. CALM has that axis today, and the view axis is the one still open.

What comes next

This is a first step. I will work to add CALM to fluxrig. The aim is one model with four jobs:

• It validates the design, with the controls that an auditor reads. The current documents carry no controls yet.
• It writes the documentation.
• It draws the diagram.
• It drives a simulation.

The scenario file stays the input. CALM becomes the portable output. A format that nobody runs is not a standard, so the implementation comes first.

I did not start fluxrig to replace other systems. The open source and fintech post records that lesson. I use work that exists, and I adopt the standard.

If you work with CALM, or with architecture as code, write to me.