@alistigo/calm-to-archify

CLI that converts FINOS CALM architecture instances (.arch.json) into interactive HTML diagrams via archify.

Install

npm install -g @alistigo/calm-to-archify
# or
yarn global add @alistigo/calm-to-archify
# or
pnpm add -g @alistigo/calm-to-archify

As a dev dependency:

npm install -D @alistigo/calm-to-archify

Requires Node.js ≥ 18.

Commands

build (default)

Full pipeline: CALM JSON → archify JSON-IR → standalone HTML.

calm-to-archify systems/*.arch.json
calm-to-archify build systems/*.arch.json

Shell glob expansion passes all matched files as positional arguments. Each file produces two outputs next to the source: <unique-id>.archify.json and <unique-id>.archify.html.

Options

| Flag | Description | |------|-------------| | --output-dir,-o <dir> | Write outputs to <dir> instead of each file's own directory |

calm-to-archify systems/*.arch.json --output-dir .archify-out

transform

CALM JSON → archify JSON-IR only (no HTML rendering).

calm-to-archify transform path/to/my.arch.json --output path/to/output.archify.json

Options

| Flag | Description | |------|-------------| | --output,-o <path> | Output path for the archify JSON file (required) |

Input format

Accepts CALM architecture instances — files that contain nodes and relationships at the top level. Pattern files (.pattern.json) are JSON Schema documents and are not supported.

Customising node-type colors and legend labels

If your CALM documents use custom node-types (from a CALM extension), add an x-archify entry to the document's metadata array to control how each type is rendered:

{
  "metadata": [
    {
      "x-archify": {
        "node-types": {
          "module": { "component-type": "backend",  "legend-label": "Module" },
          "plugin": { "component-type": "external", "legend-label": "Plugin" },
          "skill":  { "component-type": "cloud",    "legend-label": "Skill"  }
        }
      }
    }
  ]
}

See docs/x-archify-metadata.md for the full reference — available component types, legend label overrides, node sublabel and tag mapping, fallback behaviour, and the exported TypeScript types and JSON Schema.

Diagram types and 1→N output

archify supports 5 diagram types: architecture, workflow, sequence, dataflow, and lifecycle. calm-to-archify currently produces only architecture diagrams (1→1 mapping). Support for deriving additional diagram types (flows, lifecycles) from the same CALM file — producing multiple HTML outputs — is planned.

See docs/archify-diagram-types.md for the full reference: all supported types, the planned 1→N output naming convention, and click panel customisation via sources.

About CALM

CALM (Common Architecture Language Model) is an open standard from FINOS for describing software architectures as machine-readable JSON. It lets you capture nodes (services, datastores, people) and the relationships between them in a way that can be validated, queried, and visualised automatically.

About archify

archify is an open-source tool that turns a structured JSON description of a system into a fully interactive standalone HTML diagram — no server required, no external dependencies at runtime. calm-to-archify uses archify under the hood to produce the HTML output.

Thanks

A big thank you to the FINOS CALM team for building and maintaining an open, vendor-neutral standard for architecture-as-code — making tooling like this possible.

And to the archify team for creating a lightweight, dependency-free renderer that turns plain JSON into beautiful interactive diagrams — great work.