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.

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

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

Loading diagram…

Browse a product (cache miss)

Interfaces13 connections

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 bar under the picture says what each step is doing, 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 at the top of the timeline.
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 bar 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 bar, the slider, the list of steps, the panel and deep links.