The Common
Architecture Language Model.

A minimal model, visualised

Three nodes, two relationships, one control. The same model is renderable as a C4 container diagram or as a Mermaid graph — CALM is the source, the diagrams are views.

The CI/CD checkpoint

CALM validation drops into the same pipeline as your unit tests and SAST scans. A pull request that breaks the pattern fails at the same gate as a pull request that breaks a test.

1. Preflight — check what is already installed

   Run the loop below once. It probes every binary the rest of this section installs and prints ok with a version or missing. Each subsequent step is safe to skip if its binary reports ok at a recent enough version (Node 18+, Java 21+ for CALM Hub).

   bashCopy

   # report which prerequisites are present on this machine
   for cmd in curl gpg make git node npm calm java mvn; do
     if command -v "$cmd" >/dev/null 2>&1; then
       ver=$("$cmd" --version 2>/dev/null | head -n1)
       printf "  ok       %-6s  %s\n" "$cmd" "$ver"
     else
       printf "  missing  %-6s  -\n"   "$cmd"
     fi
   done

   Typical output on a fresh Ubuntu 26.04 box:

   outputCopy

     ok       curl    curl 8.5.0 (x86_64-pc-linux-gnu)
     ok       gpg     gpg (GnuPG) 2.4.4
     missing  make    -
     ok       git     git version 2.43.0
     missing  node    -
     missing  npm     -
     missing  calm    -
     missing  java    -
     missing  mvn     -

2. Update apt and install prerequisites

   Refresh the package index and install the small set of tools we need to bootstrap Node. Skip this step if the preflight reported ok for curl, gpg, make, and git — ca-certificates is preinstalled on Ubuntu Server images.

   bashCopy

   # refresh index, install build essentials and curl
   sudo apt update
   sudo apt install -y curl ca-certificates gnupg build-essential git

3. Install Node.js 22 from NodeSource

   Ubuntu 26.04 ships a recent Node in apt, but it tracks Debian’s snapshot and can drift from the active LTS. Use the NodeSource repository to pin Node 22.x — the CLI requires Node 18+, and Node 22 is the current LTS line (Node 20 reached end-of-life in April 2026). Skip this step if the preflight reported ok for both node and npm at v18 or newer.

   bashCopy

   # add NodeSource repo and install Node 22
   curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
   sudo apt install -y nodejs

4. Verify Node and npm

   Confirm both binaries are on PATH and reporting a version on the 22.x line.

   bashCopy

   node --version
   v22.14.0
   npm --version
   10.9.2

5. Install the CALM CLI globally

   Pull the official package from npm. The binary is exposed as calm. Skip if the preflight already reported ok for calm — re-run only to upgrade.

   bashCopy

   npm install -g @finos/calm-cli

6. Verify the CLI

   Print the version and the top-level command list.

   bashCopy

   calm --version
   calm --help
   
   Commands:
     generate   Generate an architecture instance from a pattern
     validate   Validate an architecture against a pattern (+ controls)
     template   Render a template using a CALM document as input
     docify     Generate a documentation site from an architecture
     init-ai    Bootstrap AI-assistant config (Claude, Copilot, Kiro)

7. Optional — install Java 21 and Maven for CALM Hub

   Only required if you intend to run the CALM Hub registry/visualisation server locally. It is a Quarkus application and will not start without Java 21+ and Maven 3.8.6+. Skip if the preflight reported ok for both java (21 or newer) and mvn.

   bashCopy

   sudo apt install -y openjdk-21-jdk maven
   java --version
   mvn --version

8. Optional — clone the reference repo for example patterns

   The FINOS monorepo carries the spec, reference patterns, and the conference-signup tutorial used below.

   bashCopy

   git clone https://github.com/finos/architecture-as-code.git
   cd architecture-as-code/calm/getting-started
   ls -1 *.json
   conference-signup.pattern.json

Common installation issues

1. Locate the pattern

   The FINOS monorepo bundles a reference pattern for a simple attendee-registration system. The pattern is a JSON Schema describing the shape of a valid architecture.

   bashCopy

   cd architecture-as-code/calm/getting-started
   ls -1
   conference-signup.pattern.json
   README.md

2. Generate a concrete architecture

   calm generate walks the pattern and produces a stub architecture document. The output is your starting point — you then fill in the populated values (real ids, owners, hostnames).

   bashCopy

   calm generate \
     --pattern ./conference-signup.pattern.json \
     --output  ./conference-signup.arch.json
   
   [calm] reading pattern: conference-signup.pattern.json
   [calm] resolved 3 nodes, 2 relationships
   [calm] wrote: conference-signup.arch.json

3. Validate

   calm validate checks the architecture against the pattern (schema conformance) and against any attached controls. In CI this is the failing gate.

   bashCopy

   calm validate \
     --pattern      ./conference-signup.pattern.json \
     --architecture ./conference-signup.arch.json
   
   [calm] schema check     ............ OK
   [calm] node id uniqueness ........... OK
   [calm] relationship references ...... OK
   [calm] controls                ...... OK
   [calm] PASS

4. Visualise with CALM Hub

   CALM Hub is the FINOS-hosted (and self-hostable) registry and visualisation server. Upload the architecture and you get a rendered topology, control overlay, and shareable URL. Either upload to hub.finos.org or run your own instance with Java 21 + Maven.

   bashCopy

   # self-host (after cloning architecture-as-code)
   cd calm-hub
   mvn quarkus:dev
     Quarkus 3.x dev mode listening on http://localhost:8080

5. Render a documentation site

   calm docify generates a static site from an architecture — nodes, relationships, controls, and embedded diagrams. The output is a folder you can publish to GitHub Pages.

   bashCopy

   calm docify \
     --architecture ./conference-signup.arch.json \
     --output       ./website
   
   [calm] wrote 12 files to ./website
   [calm] open ./website/index.html

What the architecture document looks like

Truncated to nodes and relationships for clarity — the full document also carries metadata, controls, and flow definitions. The $schema URL pins the meta-schema version used to validate.

{
  "$schema": "https://calm.finos.org/release/1.0/meta/calm.json",
  "name":    "Conference Signup",
  "description": "Reference architecture for the FINOS conference signup example.",
  "nodes": [
    {
      "unique-id":   "conference-web",
      "node-type":   "webclient",
      "name":        "Conference Web UI",
      "description": "Public-facing web interface for attendee registration."
    },
    {
      "unique-id":   "conference-api",
      "node-type":   "service",
      "name":        "Conference Signup API",
      "description": "REST API exposing attendee registration endpoints."
    },
    {
      "unique-id":   "attendee-store",
      "node-type":   "database",
      "name":        "Attendee Store",
      "description": "Relational store for attendee records."
    }
  ],
  "relationships": [
    {
      "unique-id": "web-to-api",
      "relationship-type": {
        "connects": {
          "source":      { "node": "conference-web" },
          "destination": { "node": "conference-api" }
        }
      },
      "protocol": "HTTPS"
    },
    {
      "unique-id": "api-to-db",
      "relationship-type": {
        "connects": {
          "source":      { "node": "conference-api" },
          "destination": { "node": "attendee-store" }
        }
      },
      "protocol": "JDBC"
    }
  ]
}

The resulting architecture

Architecture as Code AasC

A practice in which architecture artefacts are stored as version-controlled, machine-readable documents alongside the code they describe. CALM is its FINOS-stewarded reference specification.

CALM noun

Common Architecture Language Model. A FINOS open-source meta-schema (JSON) for describing systems as nodes, relationships, metadata, controls, and flows. v1.0 released August 2025.

FINOS org

The Fintech Open Source Foundation, a Linux Foundation project that stewards open-source software for financial services. Host of CALM and many other capital-markets projects.

AasC Community group

The FINOS working group that develops CALM. Originated from Morgan Stanley’s internal architecture-as-code effort and open-sourced through FINOS.

Node primitive

A typed entity in the model — service, database, network, actor, deployment target, or other. Identified by a stable unique-id.

Relationship primitive

A typed edge between nodes. Sub-types include connects, deployed-in, composed-of, and interacts.

Metadata primitive

Free-form key/value extension data attached to any node or relationship. The intended home for cost-centre, data-classification, and similar enterprise concerns.

Pattern noun

A reusable JSON Schema describing a class of valid architectures. The unit of reuse in CALM — e.g. a golden three-tier web app or event-driven microservice topology.

Architecture instance

A concrete JSON document that validates against a pattern and populates it with real ids, names, owners, and runtime detail. The deployable contract.

Control primitive

A declarative compliance or security requirement attached to a node or relationship. Examples: mTLS required, encryption at rest mandatory, data residency constraints.

Flow primitive

An ordered sequence of node interactions representing a business or data path — trade settlement, payment authorisation, attendee registration.

JSON Meta Schema artifact

The CALM specification itself, expressed as a JSON Schema document. Every CALM pattern and architecture validates against it.

CALM CLI tool

The command-line interface (@finos/calm-cli on npm) for generating, validating, templating, and documenting CALM documents.

CALM Hub service

The FINOS registry and visualisation server for CALM patterns and architectures. A Quarkus application, self-hostable or FINOS-hosted.

docify command

CLI sub-command that renders a CALM architecture into a static documentation website.

generate command

CLI sub-command that walks a pattern and produces a stub architecture document ready to be populated.

validate command

CLI sub-command that checks an architecture against its pattern and any attached controls. The CI gate.

init-ai command

CLI sub-command that drops Claude Code / Copilot / Kiro assistant configuration into a repo, so editors can author CALM documents with model assistance.

Drift detection practice

Periodically rendering the live system as CALM and diffing it against the approved CALM document. Surfaces unintended divergence as a PR.

SPIFFE cross-ref

Secure Production Identity Framework For Everyone. A workload identity standard frequently referenced from CALM controls when describing east-west authentication.

• CALM — Official site Specification, releases, reference patterns, and CALM Hub access.
• architecture-as-code — GitHub monorepo Source for the spec, CLI, Hub, reference patterns, and the conference-signup tutorial used above.
• @finos/calm-cli — npm package The CLI distribution. Install target for npm install -g.
• FINOS — Fintech Open Source Foundation Programme landing page. Other relevant projects: Common Domain Model, Morphir, Symphony, Waltz.
• Morgan Stanley — CALM v1.0 announcement Background on the donation and the AasC community. Search the FINOS blog or Morgan Stanley engineering blog for the August 2025 release post.