docs: live CALM diagrams in learn tutorials (2-page demo)

[gjs-opsflo]

Description

Part of #2928 (PoC tracking issue — accept/extend or discard is decided there).

Draft — a 2-page demo for feedback before doing the full learn track.

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". This demo adds live diagrams (via @finos/calm-docusaurus-plugin, merged in #2854/#2909) to two pages:

• Beginner → Build a Complete Architecture: the finished e-commerce architecture renders at the end of the page, with the composed-of platform boundary drawn as a nested container (feat(calm-suite): render composed-of and deployed-in as nested containers #2900). What you built is what you see.
• Intermediate → Model Business Flows: the order-processing flow the learner just modelled animates over the architecture — including the reverse destination-to-source transition for payment confirmation, with non-flow elements dimmed.

Both diagrams are generated at build time from committed .calm.json files (extracted from the tutorials' own JSON), so a broken tutorial architecture now fails the site build — tutorials cannot silently rot.

If this direction is agreed, the follow-up for the full track would use a single-source pattern: one .calm.json per tutorial step feeding both the code block (via raw-loader) and the diagram, so the fenced JSON and the rendered picture can never drift. Not implemented here to keep the demo dependency-free.

One renderer follow-up found while building this: the flow overlay reads a transition summary field, but the flow schema defines description — the demo files carry both; a small fix to the web component will follow so schema-only files work.

Type of Change

• 📚 Documentation update

Affected Components

• Docs (docs/)

Testing

• I have tested my changes locally
• I have added/updated unit tests
• All existing tests pass

Evidence: npm run build --workspace docs green on current main; both pages emit the pre-rendered SVG in their built HTML; the flows page hydrates to the animated overlay in the browser.

Checklist

• My commits follow the conventional commit format
• I have updated documentation if necessary
• I have added tests for my changes (if applicable) — docs-only; the site build is the test
• My changes follow the project's coding standards

[gjs-opsflo]

@karlmoll @rocketstack-matt — keeping this as a draft on purpose. Since you are reworking the tutorials/learning area, I did not want to touch the full track without checking the direction first. This adds live diagrams to just two pages as a taste: the beginner complete-architecture page now shows the learner what they built (with the platform boundary as a nested box), and the business-flows page animates the flow they modelled. If this feels right for the learn area, happy to do the full track with the single-source pattern described in the description — and equally happy to park it or reshape it around your rework. Could bring it to the next office hours for a quick look.

[jimthompson5802]

This part of the flow is not described in the body of the tutorial

[jimthompson5802]

@gjs-opsflo I see the correction for the order processing flow and the addition of the inventory flow to show bi-directional traversals.

Any chance that the CalmDiagram can be made larger for the inventory flow. The bi-directional nature is not obvious because the two nodes are are close and the sequence identifiers "2" and "3" are not visible on the live diagram. Looks like these are being overlaid by the other identifers "4" and "5".

The native sequence diagram with the existing CALM Preview makes the bi-directional flows more obvious

[gjs-opsflo]

@jimthompson5802 thank you — the overlapping identifiers and the "bi-directional is not obvious" points were both right, and both are now fixed in the renderer. Here is what changed:

1. Each transition now draws its own arrow. Before, the flow was shown as one gray edge with number badges on top — the numbers could overlap and the direction was not visible. Now every transition is a blue arrow with its own arrowhead. When a relationship carries traffic both ways (like the inventory check: request 2/3 down, response 4/5 back up), the two directions split into two parallel arrows. So bi-directional is visible from the geometry itself, not from reading the numbers.

Inventory flow — request lane down (2, 3 solid), response lane up (4, 5 hollow):

Order flow — all forward, each step has its own arrow and the identifier sits on the arrow:

2. Identifiers cannot overlap anymore. Same-direction identifiers are spread along the arrow by sequence order, so "2" and "3" cannot sit under "4" and "5" like in your screenshot.

3. Diagram size. When a flow is active, the layout now spaces the nodes wider automatically, so the arrows have room. No manual sizing needed.

4. On your sequence diagram point — agreed it is the clearest form for reading a flow step by step, so it is now available as an opt-in on the same component: <CalmDiagram src="..." flow="inventory-check-flow" flowView="sequence" /> renders the flow as a proper sequence diagram (participants, lifelines, one arrow per step), pre-rendered at build time. The topology view stays the default because it keeps the flow in the context of the full architecture, and the two views come from the same JSON, so they cannot drift apart.

here is a sequence view rendered

The PR branch will be updated with these renderer changes once the base PR (#2939) lands. Thanks again for testing this on a real machine — both catches improved the renderer for every CALM diagram, not only this demo.

[rocketstack-matt]

@gjs-opsflo is this PR still in progress?

[rocketstack-matt]

@gjs-opsflo please reopen if you're able to get the failing build resolved and comments closed out.