Playback, sharing and the step list

Everything a reader does with a scenario happens in the player under the diagram and in the step list below it.

OverviewBackend only

Everything in one picture. Letters on the edges match the interfaces table underneath.

ScenarioOverviewBrowse a product (cache hit)Browse a product (cache miss)Place an orderCard declined

The shopper pays. The order is stored first, charged second, and announced to the rest of the system last.

HTTP request / responseData accessPersistent channel (websocket, gRPC)Queue / brokerDashed: planned

Loading diagram…

ISubmit

1

Shopper browser→order-servicevia CDN, API gatewayPOST /orders

The gateway has already checked the token, so the order service trusts the user id header.

2

order-service→PostgreSQLINSERT order (pending)

IICharge

3

order-service→Stripecreate payment intent

4

Stripeauthorise card

5

Stripe→order-servicesucceeded

IIIFinish

6

order-service→PostgreSQLmark paid

7

order-service→RabbitMQorder.created

8

order-service→Shopper browservia API gateway, CDN201 Created

9

RabbitMQ→notification-workerorder.createdplanned

Planned. Confirmation emails are not sent yet.

Key	From → To	Kind	Auth	What travels
A	Shopper browser → CDN	http	—	HTTPS
B	CDN → API gateway	http	—	—
C	API gateway → Keycloak	data	client credentials	signing keys
D	API gateway → catalog-service	http	—	/products
E	API gateway → cart-service	http	—	/cart
F	API gateway → order-service	http	—	/orders
G	catalog-service → Redis	data	—	cache
H	catalog-service → PostgreSQL	data	—	—
I	cart-service → Redis	data	—	—
J	order-service → PostgreSQL	data	—	—
K	order-service → Stripe	channel	API key	payment intent
L	order-service → RabbitMQ	queue	—	order.created
M	RabbitMQ → notification-worker	queue	—	—

Shopper browser

React storefront

CDN

static assets · TLS

API gateway

:443 · rate limit

verifies the JWT

routes by path

Keycloak

OIDC · realm shop

catalog-service

:4001 · Node.js

products

prices

search

uses: redis · postgres

cart-service

:4002 · Go

session carts

uses: redis

order-service

:4003 · .NET

creates and tracks orders

talks to the payment provider

uses: postgres · rabbitmq

notification-worker

email and push

planned

Redis

catalog cache · carts

PostgreSQL

orders · products

RabbitMQ

order.events

Stripe

payment provider

The player

Control	What it does
Play, Pause, Resume, Replay	Runs the scenario. The button’s label says what it will do next.
Previous step, Next step	Moves one step at a time. If a step is half played, Next finishes it first.
Scrubber	Drag to any moment. Playback pauses while you scrub.
Speed	0.5×, 1× or 2×.
Flow, Sequence, Story	Switches how the scenario is drawn. See story and sequence.

The player also shows where you are: step 3/9 · 0:04.

The step list

Every step is listed under the player, grouped by phase. The step in progress is highlighted, finished steps are marked, and notes appear under their step. A multi-hop step names the nodes it passes through (“via CDN, API gateway”).

Click a step to play it. The path already travelled stays lit, so a reader can jump to the middle of a story and still see how it got there. The list is also keyboard-friendly: Tab to a step and press Enter or Space.

Follow

On a large diagram the whole picture is small, so the camera can follow the action. A Follow button appears while a scenario is selected. Following starts on automatically when the diagram is wider than 1500 px or taller than 950 px, and stops as soon as the reader pans or zooms. Press it again to bring it back.

Links to a moment

The address bar follows the scenario and step, so readers can share exactly what they are looking at:

https://example.com/examples/checkout/#checkout=place-order.4

The format is #<diagram>=<scenario>[.<step>], where the step is the number shown in the step list. A page with several diagrams joins them with &:

#checkout=place-order.4&payments=pay.2

Opening such a link selects the scenario, switches to its view, and shows the step already played, paused, so the reader decides when to continue.

Note

The address updates when playback stops, not on every frame. Embeds that should not touch the address, such as a decorative demo, can pass hash={false}. See the Diagram component.

Autoplay and reduced motion

A scenario a reader clicks starts playing. One that a page selects with scenario="..." waits, unless the page also passes autoplay:

<Diagram name="checkout" scenario="place-order" autoplay />

Readers who ask their system for reduced motion are never autoplayed, and clicking a scenario selects it without playing. They can still press Play, step through, or scrub.

How it works

A scenario compiles to a timeline: for every step, when it starts and ends, and for every hop, when the packet is on which edge. frameAt(t) is a pure function that turns a time into a picture: which packets are where, which nodes are lit. The player is only a clock that advances t. That is why scrubbing, stepping, deep links and the tests are all exact. See how it works inside.