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.
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. It counts more than 100 member organizations and over 50 open projects and standards. Its governing board comes from the banks and vendors that must live with the result. That last point is the difference. 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.
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:
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:
1
2
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.
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.