finos / finos/architecture-as-code
[PoC] Live CALM diagrams in the learn tutorials
- 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
Assessment
This issue has not been assessed yet.