CALM Widgets - Simplified Handlebars Template Library for Architecture Documentation

[rocketstack-matt]

Feature Proposal

Target Project:

CALM Monorepo - New calm-widgets project to be integrated into the existing monorepo structure and used by the CLI

Description of Feature:

The CALM CLI already provides a Handlebars integration. Whilst the existing implementation is extremely powerful and allows for multiple complex target output formats such as Docusaurus websites and Infrastructure as Code manifests, it is overly complex for architects wanting to embed elements of their CALM architecture into markdown documents.

This proposal addresses the need for a more streamlined and accessible way to generate documentation from CALM architecture files.

Desired Capabilities:

• Simplified Template Syntax: Intuitive property access using {{ architecture.metadata.name }} instead of complex helper functions
• Bracket Notation Support: Easy node access with {{ architecture.nodes['api-gateway'].description }}
• Schema-Based Controls: Automatic fetching and parsing of control requirement schemas from URLs
• Array Indexing: Support for accessing array elements with {{ architecture.nodes['api-gateway'].controls.cbom.requirements[0] }}
• Intelligent Table Generation: Automatic table formatting for nodes, controls, metadata, and individual control requirements
• CLI Integration: Seamless integration with CALM CLI for template processing

User Stories:

• As a solution architect, I want to generate beautiful documentation from my CALM architecture files so that I can share readable architecture descriptions with stakeholders
• As a developer, I want to use simple, intuitive template syntax so that I can quickly create custom documentation templates without learning complex Handlebars helpers
• As a technical writer, I want to access specific architecture components by their unique IDs so that I can create focused documentation for individual services or systems
• As a DevOps engineer, I want to integrate CALM documentation generation into my CI/CD pipeline so that architecture documentation stays up-to-date automatically

Current Limitations:

Currently, the CALM ecosystem lacks:

• Simple, intuitive template syntax - current approaches require deep Handlebars knowledge
• Support for schema-based control requirement documentation
• Easy access to specific architecture components by their unique IDs
• Built-in widgets for common documentation patterns (tables, lists, metadata display)

Proposed Implementation:

We propose to implement this feature with the following technical approach:

Technical Architecture:

• Project Structure: Create a standalone calm-widgets project within the monorepo
• Template Engine: Extend Handlebars with custom helpers and preprocessing capabilities
• CLI Integration: Integrate directly with the existing CALM CLI template command

Proposed API Design:

// CLI Integration
calm template --input ./architecture.json --template my-template.md --output ./docs

// Template Syntax Examples
{{ architecture.metadata.name }}
{{ table architecture.nodes filter='node-type:service' }}
{{ architecture.nodes['api-gateway'].controls.cbom.requirements[0] }}

[LeighFinegold]

@rocketstack-matt thanks for moving this forward. Everything in PR #1417 – Initial implementation of calm-widgets lines up with the goal of making one‑pager document generation friction‑free.

---

1️⃣ Where should the new code live?

We need to decide how much of the PR’s logic should

• live in a dedicated @calm/widgets package, versus
• fold back into the core CLI/shared tooling (which already hosts the template engine, model/schema definitions, and JSON document dereferencing for when architects leverage detailed-architecture or control-config-url).

A clean split keeps extension points obvious (teams can add their own helpers or company‑specific CLI wrappers – see #1116) while letting the first‑party CLI stay zero‑config for newcomers.

---

2️⃣ Bundles and the Default Transformer – invisible for the quick path

Bundles remain essential for multi‑file output and partial reuse, and the new DefaultTransformer (from #1106) means users no longer need to declare their own transformer. Together, the CLI can hide almost all boilerplate for quick docs:

calm template \
  --input ./architecture.json \
  --template my-template.md \
  --output ./docs       # CLI injects a default bundle + DefaultTransformer

---

3️⃣ Built‑in helpers + a JSONPath helper

Right now templates already have helpers such as:

{{ architecture.metadata.name }}
{{ json architecture.controls }}

We could extend this with a JSONPath helper to simplify ad‑hoc document traversal:

jsonpath: (obj: any, expr: string) => {
 return jp.query(obj, expr);
}

---

4️⃣ Relaxed binding reduces likely tooling upgrade.

The PR introduces another model in calm-widgets/src/types/index.ts, but the implementation effectively binds Handlebars to the raw CalmCoreSchema rather than an additional abstraction layer.
Technically the Transformer interface is flexible - see types.ts#L17 but default provided transformers in docify and tempalte add the abstraction layer model e.g. default transformer

This approach makes it painless to surface new artefacts—e.g. a future timelines.json (#1409)—without breaking existing template bundles. It may also reduce (or even remove) the need to publish a separate @calm/model package (see #1116), because template authors can work directly against the existing schema shape.

---

5️⃣ Widgets: the natural home for common partials

A standalone @calm/widgets package cleanly demonstrates registerHelper/registerPartial usage. It also supersedes the “always‑include” partials idea in #1033, because shared partials would simply live here and be pulled in via globalPartials.

The Docify bundle already contains diagram partials for flows and relationships—ideal candidates to extract into widgets immediately.

I think one thing that we need to maintain is when the schema changes. The widget templates would likely need to change as well. Alternatively, widgets are backed by a intermediary viewmodel and the focus becomes on upgrading transformers to the viewmodel as the schema progresses.

---

🔜 Proposed next steps

1. Agree on the split (core vs widgets) so contributors know where to extend.
2. Wire the CLI to default to the auto‑bundle + DefaultTransformer path shown above.
3. Extract the existing diagram partials into @calm/widgets and publish alongside @calm/core and the slimmed‑down @calm/cli, all versioned together.
4. Relax the model mapping in calm-template to the 1‑to‑1 schema shape defined in shared/src/types (reducing pressure to publish a separate model package).
5. Clarify v‑1 scope: we’ve heard these improvements may be “out of scope” for the v‑1 milestone. Let’s decide explicitly whether to fold them into v‑1 or schedule them post‑v1 so we can plan resources and messaging.

---

Exciting times ahead for CALM—keen to discuss with the wider group in the next office hours! 🙌