Phases and notes

A long scenario is easier to follow when it is broken into phases: “Record it”, “Charge the card”, “Finish”. Phases appear as numbered headers in the timeline, as sections in the sequence diagram and as horizontal bands in the story view, and a reader can fold each one away.

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

Loading diagram…

scenarios:
  pay:
    title: Pay with a card
    summary: |
      The shopper pays. We write the payment down **first**, charge the card **second**,
      and tell the rest of the system **last**, so a crash never loses money.
    phases:
      - title: Record it
        caption: before any money moves
        steps:
          - web -> api:
              label: POST /payments
              note: The request carries an idempotency key, so a retry cannot charge twice.
          - api -> db: { label: INSERT payment (pending), kind: lookup }
      - title: Charge the card
        steps:
          - api -> stripe: create payment intent
          - at stripe:
              label: authorise card
              note: This is the only step we do not control, and the slowest one.
          - stripe -> api: succeeded

Phases

A phase has a title, an optional caption and its steps.

Field	Meaning
`title`	Required. Plain words: “Submit”, “Charge”, “Finish”.
`caption`	A short note shown after the title: “before any money moves”.
`steps`	Required. At least one step.

Aim for two to five phases. A scenario may use steps: or phases:. Without phases, the timeline is flat and no bands are drawn.

Folding phases

A reader can fold a phase away to see the shape of a long story, or to skip what they already know. In the list of steps, click the header of a phase; in the sequence, click its section; in the story, click the numeral of its band. A folded phase becomes one thin line that still says what it is and how many steps it holds, and while the scenario plays through it, how far it has got. Folding never changes what plays, and it is shared by the three ways of drawing a scenario. See the steps.

This is the reason to give phases real titles: a title is what is left to read once the steps are folded away.

Summary

summary is Markdown shown at the top of the timeline when the scenario is selected. Write the story in a sentence or two, with the one fact that matters in bold. In the story view it is framed as “The story in one breath”.

Notes

note is Markdown shown under the step in the timeline. Use it for the why:

- browser -> orders:
    label: POST /orders
    note: >
      The gateway has already checked the token, so the order service
      trusts the `X-User-Id` header.

Notes support emphasis, inline code, lists and links. Raw HTML is dropped. A step with a note is the right place to say what could go wrong, who owns the step, or why it is ordered the way it is.

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…

Flat scenarios

If you do not need phases, a flat steps: list is fine. Short stories read well that way.

scenarios:
  load-page:
    title: Load a page
    steps:
      - browser -> api: GET /items
      - api -> browser: 200 OK