Telling a story

A scenario is an ordered list of steps. Each step sends a packet along your edges, or makes one node do something. A diagram can have as many scenarios as you like, and readers pick one above the canvas.

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 product is not cached yet, so the catalogue reads PostgreSQL and fills the cache for the next shopper.

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

Loading diagram…

IThe request

1

Shopper browser→catalog-servicevia CDN, API gatewayGET /products/42

IICache miss

2

catalog-service→RedisGET product:42

3

Redis→catalog-servicemiss

4

catalog-service→PostgreSQLSELECT product

5

PostgreSQL→catalog-servicerow

6

catalog-serviceSET product:42 ttl 60s

The next request for this product is a hit.

IIIThe answer

7

catalog-service→Shopper browservia API gateway, CDN200 + JSON

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

Press Play. The packet flies, the step list under the player follows along, and the boxes the story has visited stay lit.

The smallest scenario

scenarios:
  load-page:
    title: Load a page
    steps:
      - browser -> api: GET /items
      - api -> db: { label: SELECT, kind: lookup }
      - db -> api: rows
      - api -> browser: 200 OK

A scenario needs a title and either steps or phases. Its id (load-page) appears in deep links.

What a scenario can have

Field	Meaning
title	Required. The button’s label.
summary	Markdown: the story in a sentence or two, shown above the diagram.
steps or phases	The steps, flat or grouped. See steps and phases.
view	The view it plays on. Defaults to the first view.
mode	How it opens: flow (default), sequence or story.
lanes	The columns of the story view.

Where scenarios live

Short ones fit inside diagram.yaml. A long one can live in its own file. Every diagrams/<name>/scenarios/<id>.yaml becomes a scenario with that id, and the file holds the scenario’s fields directly:

diagrams/platform/scenarios/device-offline.yaml

title: Device is offline
summary: The job waits in the queue until the device reconnects.
phases:
  - title: Dispatch
    steps:
      - backend -> control-api: enqueue job

Defining the same id in both places is an error.

Three ways to read the same steps

Every scenario can be shown as packets over the architecture (Flow), as a Sequence diagram, or as a swimlane Story. The player has a button for each, and mode: picks which one a scenario opens in. You write the steps once.

Story viewSwimlanes with phases and plain-language boxes. The one for newcomers.

Sequence viewA classic sequence diagram generated from the same steps.

Writing scenarios worth watching

• One story per scenario. Show failures as their own scenarios (payment-declined), not as footnotes to the happy path. Readers learn the most from the failures.
• Start with the happy path. Then add the two or three failures that teach something about the design.
• Give every scenario a one-sentence summary. It is the first thing a reader sees.
• Keep it to what a reader can follow, roughly 6 to 15 steps. Group longer ones into two to five phases with plain titles such as “Submit”, “Charge” and “Finish”.
• Label what travels: POST /orders, order.created, 200 OK. Explain why in a note:, not in the label.

Pages in this section

StepsFlow steps, self steps, kinds and options.

Phases and notesGroup steps, add captions and explanations.

Parallel steps and routesThings that happen together, and how packets find their way.

Playback and sharingThe player, the step list and deep links.