finos / finos/architecture-as-code

[PoC] Live CALM diagrams in the learn tutorials

Open
#2,928 4 comments 0 reactions 1 assignee Claimed by @gjs-opsflo View on GitHub
Roadmap Group: Proof of Concepts
Dominant language
TypeScript
Stars
399
Forks
138
Avg merge
2d 14h
Merged PRs (30d)
37

Description

## What this PoC explores

The learn tutorials teach people to build CALM architectures step by step, but the learner never sees what they built — they paste JSON and read "validation succeeded with 4 nodes". Now that live diagrams work in the docs site (#2854, #2900, #2909), this PoC explores embedding them in the learn track: after each step, the learner sees the architecture they just wrote, rendered from the same kind of `.calm.json` file they are editing.

## The experiment

Draft PR #2921 adds live diagrams to **two pages only**, as a taste:

- **Beginner → Build a Complete Architecture**: the finished e-commerce architecture renders at the end of the page, with the platform boundary drawn as a nested container.
- **Intermediate → Model Business Flows**: the order-processing flow the learner modelled animates over the architecture, non-flow elements dimmed.

Both diagrams are generated at build time from committed `.calm.json` files, so a broken tutorial architecture fails the site build — tutorials cannot silently rot.

## How we decide

This follows the run-an-experiment-then-decide style: the draft PR is the experiment, this issue is where we decide.

- **Accepted** → extend to the full learn track, using a single-source pattern (one `.calm.json` per step feeding both the code block via `raw-loader` and the diagram, so fenced JSON and the picture can never drift), and fix the small renderer follow-up found on the way (flow overlay reads `summary`, the flow schema defines `description` — renderer should accept both).
- **Not the right fit** → close this and the draft, no harm done. Especially open to reshaping around the tutorials/learning rework @karlmoll has in progress.

Happy to demo at office hours.

Related: #2921 (the draft PR), #2853 / #2854 / #2900 / #2909 (the docs-embed work this builds on).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.