POC: Live Flow Sequence Diagrams in CALM Hub

> Interested in being involved in this PoC? Add a comment on this issue.
> Are you a maintainer who wants to help guide development? Please chip in by commenting on this issue too.

Executor of POC: @LeighFinegold, @aidanm3341

## Aim

Prove end to end that a CALM flow can be authored in a workspace, published to CALM Hub like any other artefact, then picked in the Hub and watched as a live sequence diagram: playing over its architecture one step at a time, with play, pause, step and scrub. Today a flow shows only raw data in the Hub and cannot be published from a workspace at all. The view builds on the Hub's existing diagram so the platform moves toward one shared way of drawing CALM, and the flow doubles as a live example of what the model needs to describe richer sequences, giving evidence for #2950 without changing anything yet.

## Objectives

1. Publish a flow to the Hub from a workspace, using the author and push experience that already works for architectures and patterns.
2. Show a flow in the Hub as a live diagram over the architecture it runs on, so each step has real participants instead of raw data.
3. Let people drive the sequence: play, pause, step forward and back, and scrub, in the order the flow defines.
4. Build on the Hub's own diagram rather than adding a second way of drawing CALM.
5. Capture what the flow model needs for richer sequences, as evidence for #2950.
6. Show the whole cycle, authoring to playback, against a local Hub.

## Background & decision record

- #2537 Visualize Flow Sequence Diagrams in CalmHub. Asks for a flow view; as proposed it is a static list of steps. This epic re-aims it at a live diagram you can step through.
- #2983 Publish documents to CALM Hub via calm workspace. Architectures and patterns already publish from a workspace and the Hub already accepts flows, but the workspace tool does not offer it for flows yet; this closes that gap.
- #2950 Add Sequence Diagram Support to CALM. CALM already draws sequence diagrams from the flow model; richer sequences (clear ordering, concurrent steps, named participants, branching) would need the model to grow. A live view is the best way to find what is missing, so this PoC feeds that discussion without changing the model.
- Flows moving out of core.json (finos/calm-schema#20). Today a flow can only live embedded inside an architecture; this change lets an architecture reference a flow that stands as its own document. That is what makes authoring, publishing and versioning a flow on its own valid, and it keeps flows a first-class part of the schema rather than a decorator, matching the documents-versus-decorators decision in #2791.
- Platform convergence (#2600, #2690). The tools draw CALM in several ways and there is an effort to share one; this PoC builds on the Hub's diagram so the flow view lands on that path rather than adding another.
- Live CALM diagrams on the docs site (#2854, #2909, #2921, #2928). CalmStudio's diagram already animates a flow over an architecture; treated here as the experience to match, not something to embed.
- #2905 Office Hours 2026-07-30. Set the PoC process: raise as issues, state outcome and scope, apply a `POC` label.

## Value cycle

```mermaid
flowchart TD
A0["Author a flow in a workspace"]
A["CALM Hub
the flow, published and versioned like other artefacts"]
B["Connect the flow to its architecture
match each step to a real connection and its participants"]
C["Live diagram in the Hub
step through the flow in order; pause and scrub"]

A0 -->|"publish from the workspace"| A
A -->|"select the flow"| B
B -->|"flow shown on its architecture"| C
```

## Scope

In scope (minimum viable slice):
- Publishing a flow to the Hub from a workspace, like other artefacts.
- A flow view that plays the sequence as a live diagram, with a list of steps as a fallback.
- Drawing the flow over one chosen architecture so steps have real participants.
- Stepping in the order the flow defines, including steps meant to happen together.
- A local demo against a standalone Hub, plus a note on what the flow model was missing.

Out of scope (follow-ups):
- Diffing or comparing flows to show what changed between versions; that flows are not compared is a known tooling gap (#2998) and a follow-up, not this PoC.
- A permanent stored link from a flow to its architecture; the PoC recommends an approach and feeds the #2537 follow-up and the flows-as-reference direction in finos/calm-schema#20.
- Finishing the shared-diagram work; the PoC builds on the Hub view and aligns with it.
- Behaviour and BDD views of flows (#2627, #2624, #2625, #2611).

## Constraints & guard-rails

- Do not redesign flow storage; flows are already a first-class, versioned Hub resource.
- Do not change the flow model here; what the live view needs is recorded as evidence for #2950, and landing that change is the separate follow-up through the normal schema-change process.

## Definition of done

- A user can author a flow in a workspace, publish it, and open it in the live view.
- Selecting a flow plays it over its architecture, stepping in order with pause and scrub.
- The flow view reuses the Hub's own diagram, not a separate one.
- A local demo shows the full cycle, with a note on how a flow should point at its architecture and what the model needs for richer sequences, feeding #2950.

## Related issues

- #2537 Visualize Flow Sequence Diagrams in CalmHub (anchor, re-aimed from static to live)
- #2950 Add Sequence Diagram Support to CALM (the flow model growth this informs)
- finos/calm-schema#20 Allow the flows array to be a reference (flows detached from core.json, so a flow can stand as its own document)
- #2791 Design Discussion: Documents vs Decorators (flows stay first-class, not a decorator)
- #2983 Publish documents to CALM Hub via calm workspace (the publishing precedent this follows)
- #2539 CALM Workspace vs CALM Hub command comparison
- #2377 CLI publishing commands for CALM Hub content
- #2600 Consolidate the CALM platform (the shared-diagram direction this builds on)
- #2690 RFC: shared CALM semantics layer to align the Hub and CalmStudio
- #2854 Live CALM diagrams on the docs site (prior art, experience to match)
- #2900 Draw nested containers in CALM diagrams (prior art)
- #2909 Embed a live CALM diagram in the docs site (prior art)
- #2921 Live CALM diagrams in the learn tutorials (prior art, draft demo)
- #2928 Live CALM diagrams in the learn tutorials (PoC tracking)
- #2998 calm diff does not compare flows (a known tooling gap; flow compare is out of this PoC)
- #2880 Run the CALM engine in the browser (optional live validation)
- #1856 Flow transitions should have required properties (flow model precedent)
- #2627 Behaviour-driven architecture for CALM (tracking)
- #2624 CALM Studio flow builder and behaviour panel
- #2625 Actor and sequence flow rendering in widgets
- #2611 Attach behaviour specs to CALM nodes and relationships
- #2905 Office Hours 2026-07-30 (PoC process)

Start with the workspace publishing path for architectures and patterns, then inspect the Hub's existing diagram and flow handling. Run the local Hub demo described in the issue to trace authoring, publishing, selection, and playback. Done means the full local cycle works with ordered play, pause, stepping, scrubbing, and a note capturing model gaps for #2950.

Written by the indexing model from the issue text.