stackmapstackmap
Install

DocsDiagram kinds

Sequence

Messages over time between a few participants, for one scenario: a request with a cache miss, an async job round trip.

Participants are the nodes, left to right in the order a request travels; messages are the edges, top to bottom in array order, each one labelled. stackmap spaces the lifelines and draws the activation bars itself.

An example

The skill’s own example, checkout.sequence.json, laid out by stackmap.

file:///…/.stackmap/checkout/diagram.html
checkout.sequence.json99 lines
{  "kind": "sequence",  "title": "Checkout request",  "subtitle": "Card payment with a fraud check",  "phases": [    {      "id": "authorize",      "label": "Authorize",      "edges": ["pay", "score", "ok", "charge", "captured"]    },    {      "id": "confirm",      "label": "Confirm",      "edges": ["receipt", "done"]    }  ],  "nodes": [    {      "id": "web",      "type": "client",      "card": { "title": "Web app", "subtitle": "Checkout page" }    },    {      "id": "api",      "type": "service",      "card": { "title": "Orders API", "subtitle": "Payments route" }    },    {      "id": "fraud",      "type": "security",      "card": { "title": "Fraud check", "subtitle": "Risk score" }    },    {      "id": "stripe",      "type": "external",      "card": {        "title": "Stripe",        "subtitle": "Payments API",        "brand": "stripe"      }    },    {      "id": "mail",      "type": "queue",      "card": { "title": "Mail queue", "subtitle": "Receipts" }    }  ],  "edges": [    {      "id": "pay",      "from": "web",      "to": "api",      "label": "POST /pay",      "tone": "main"    },    {      "id": "score",      "from": "api",      "to": "fraud",      "label": "score order",      "tone": "security"    },    {      "id": "ok",      "from": "fraud",      "to": "api",      "label": "low risk",      "kind": "return"    },    {      "id": "charge",      "from": "api",      "to": "stripe",      "label": "create charge",      "tone": "main"    },    {      "id": "captured",      "from": "stripe",      "to": "api",      "label": "captured",      "kind": "return"    },    {      "id": "receipt",      "from": "api",      "to": "mail",      "label": "send receipt",      "kind": "async"    },    {      "id": "done",      "from": "api",      "to": "web",      "label": "200 paid",      "kind": "return"    }  ]}
Point at a node in the JSON, or at its card, to find the other.

Its parts

  • Participants

    Three to eight, caller first.

  • Messages

    Every one labelled, in time order.

  • Replies

    kind return, dotted with an open head.

  • Activation bars

    Derived from calls and replies.

Rules

From the authoring contract the skill gives your agent. stackmap validate enforces the hard ones and names the fix.

  • Participants are the nodes: three to eight, left to right in the order a request travels, so the caller comes first and stores and third parties last.
  • Messages are the edges, top to bottom in array order. Label every one, briefly.
  • A call is plain; "kind": "return" is its reply, from the callee back to the caller, after it; "kind": "async" is fire-and-forget. A message to itself is a self-call.
  • Activation bars follow from the calls and replies; a reply that answers nothing is a warning, semantics/unmatched-return.
  • Phases (phases with edges) band stretches of time: Request, Fallback, Response.
  • No groups or lanes, and cards are compact.

Ask for one

Draw the request path for a dashboard load as a sequence, including the cache miss.

Your agent picks the kind that answers the question; naming it is the surest way to get it.

Examples

See sequence examples in the gallery