USER MANUAL · FLOWS & SEQUENCES

Request flows

A flow is a named sequence of steps, and its steps are the edges a request rides, in order. Flows are named for what they do: “Place an order”, “Daily reprice”. Every step carries a caption, which the stepper shows as you walk. A step can light several edges at once (a parallel fan-out). A flow can also include operations inside a node, such as “validate the cart” or “compose the payload”, which play as stops of their own with a small panel on the node.

API GatewayContainer
Order ServiceContainer
3
Place an order3 / 8

Gateway authenticates and routes to Orders.

StepsLive
A flow mid-playback: the current step's edge runs gold with its position badge, and the stepper narrates. Steps can light several edges at once, and a node's internal operations play as stops too.

Playing a flow

  • Start one from the rail (flows nest under their canvas) or via ⌘K. The stepper appears bottom-left; step with ← / → or its arrows, leave with Esc or Exit flow. The two pills on it are the mode — Steps or Live; the arrow keys belong to Steps.
  • Reveal (Steps only) draws only what the flow has reached: anything a later step introduces waits its turn, and arrives exactly where it will stay — nothing on the canvas moves. It rides the URL as reveal=1, so a link and a presentation carry it.
  • Steps mode walks the sequence: numbered chips on the edges, the active edge carries a gold particle, everything off-path dims, and the camera follows each stop.
  • Live mode plays the same flow over real health: healthy paths run gold, and a path through a node that is down stops red at that hop, with the stepper reading “Blocked at step 5”. Polling tightens to a few seconds while you watch. See Live health.
  • A flow mid-play rides the URL (flow= and step=) — Copy link hands a collaborator the exact stop you're on. In a presentation, viewers follow your stepping live.
  • While a flow is active, the Export menu offers a flow scope: only the participants and edges of this flow, framed as rendered.

Sequence view

  • The Sequence view pill in the tool rail draws the same flow two ways. Sequence puts the participants across the top as columns and the stops down the page as rows, numbered exactly as the diagram numbers them; clicking a row is the same navigation as ← / →, and the flow and the stop you are on survive the switch either way.
  • Live mode reads the same there: every healthy message runs gold, a participant that is down colors its whole column, and every message that touches it is drawn red as blocked. The outage and the requests it stops are one picture, and the diagram and the sequence agree on what is down.
  • Column headers carry the same unread-comment badge a node wears on the diagram, with the same count; click it and the thread opens under the header. Reading it in either drawing clears the badge in both.
  • The sequence follows the diagram's expansion: a container that is collapsed there is one column here, labelled with the container and its n children hint, and every message to or from a child routes to it. A stop entirely inside a closed container draws no row but keeps its number, exactly as the player skips it. Click the hint and the diagram opens with the column. An open container's bracket carries the diagram's collapse button at its top-right: it folds the children back into one column, here and on the diagram.
  • Export writes the columns themselves as PNG, SVG or PDF (no scope row — the picture already is the flow), and Copy Mermaid hands back that one flow's sequenceDiagram instead of the whole model.
  • The view rides the URL as view=sequence, so a link opens there on the same stop, and presentation viewers follow the switch live. New canvas → Sequence starts from a template that ships a flow — Sign-in, Order placement, Nightly batch or Blank sequence — and lands in it. It is an ordinary canvas, and the diagram is one pill away.

Editing in the sequence

  • Press Edit model while the sequence is on screen and you edit it there, on the drawing. Done editing leaves. On a canvas with no flow yet, Start a sequence makes one and opens it.
  • The sequence edits the flow, not a copy of it: Add participant puts a column in, Add operation a stop inside one, and Add message arms a two-click gesture — the chip reads Click the participant that sends, then From … — now click the receiver. Drag a stop's grip or a participant's header to reorder; the panel's arrows do the same.
  • A run of stops can sit inside a loop. Add loop arms two clicks: the chip reads Click the first stop of the loop, then Now click the last stop. The stops are boxed, with a tab at the top-left that reads LOOP and the label you type in the panel, such as until the card is accepted. The panel's Kind turns it into an opt, drawn the same way, and First stop and Last stop move its ends. The box stays on its stops when they are reordered, and the stepper names the loop a stop is in. In Mermaid it is a loop … end or opt … end block, and both import and export as the box.
  • Selecting a row or a column opens its fields in the panel on the right: Caption, Connection label and Technology for a message, Name, Kind and External for a participant. A participant offers two ways out: Remove from sequence drops the column only, Delete from the model removes the node everywhere.
  • A message between two participants that have no connection creates the connection on the diagram. A participant is a real element of the model — a node — not a drawing of one, so the diagram and the sequence can never disagree.
  • Nothing inside a collapsed container is offered as an endpoint: its column stands for its children, it neither drags nor reorders, and its inspector offers Open it. When the armed Add message picks a closed container as the sender, the chip offers to open its children first.
  • The assistant follows the drawing you are looking at: in the sequence view it edits the flow (add a step, reorder it, add a participant), and asking to “show it as a sequence” switches the drawing.
  • Every edit saves as a version like any other. Over MCP, set_flows writes a canvas's flows from sequenceDiagram text and creates any connection or participant the text names that the model is missing; see MCP.

Comparing two versions

  • From the sequence, open History and press Compare versions: the same flow at two versions lands in one drawing — added and removed steps, participants and loops, and changed captions, in the same green, red and amber the canvas diff uses, with the same legend and a tally underneath.
  • It answers the question a step list cannot: what the request path did before this change, and what it does now.

Authoring flows

  • In the editor's Flows tab: Add flow, then name it and give it a description — both show in the rail and the stepper.
  • The stop list is exactly what playback will walk. Add a step by picking the edge it rides (or several, for a parallel stop) and writing its caption; add an operation by picking the node and writing what happens inside it.
  • Reorder with the arrows on each stop row, or insert directly between two stops with the + step / + op row that appears between them. Deleting a stop never touches the edge itself — flows reference the model, they don't own it.
  • Deleting a node or edge from the model prunes it out of every flow that used it.
  • The assistant authors a complete flow from a sentence such as “show me the checkout flow step by step”, and its flows are editable here like any other.