What this example shows
A canonical sequence diagram of an HTTP /checkout POST handler - the time-ordered interactions between the Client, the Checkout Service, and every collaborator the handler touches: Auth, Redis Cache, Inventory, the Stripe Payment Provider, and a Notification Queue. The diagram includes a sequence-fragment alt around the payment retry path, a note explaining Stripe’s idempotency-key convention, an async fire-and-forget publish to the notification queue, and a self-message for the response-build step. The “before” scene captures the handler before a recent latency-improvement change (a synchronous call to the Cart Service; synchronous notification HTTP call). The “after” scene reflects the handler after it (the cart read from a Redis cache instead of the Cart Service, retry logic around payment, notifications moved to a queue). The diff between revisions is the deliverable a reviewer cares about - they see what the new code does differently without reading the code diff line by line.
When to use it
Reach for this pattern when your team has a flagship endpoint (checkout, login, payment, document-upload, anything mission-critical) whose internal call graph is hard to hold in one engineer’s head. The diagram becomes the team’s authoritative answer to “what happens when a request hits this endpoint” - used in onboarding (new engineers learn the flow without grep-walking the codebase), incident response (on-call sees which collaborator to investigate), architecture reviews (anyone proposing a change can show the structural diff alongside the code diff), and security reviews (reviewers see which third parties touch which data, in what order). Every revision is a dated snapshot of the request flow as the diagram described it, so you can see how the flow changed over time.
What the agent does
The agent reads the handler source file and its direct dependencies. When they change, it walks the handler’s async/await chain, identifies the participants (services called via SDK or HTTP, queues published to, caches read, the database, external APIs), and applies typed operations to the persisted scene: createNode for new participants, createEdge with edgeType: "sequence.message" / "sequence.reply" / "sequence.async" for new interactions, each placed with after next to the one it follows, createFrame with containerType: "fragment" for branching paths (alt for try/catch retry, opt for conditional calls, loop for iterating), and sequence.note nodes for implementation notes worth preserving in the diagram (idempotency keys, retry budgets, timeouts).
The flow is incremental. The persisted scene keeps stable lifeline and edge IDs across revisions, so the revision diff names exactly the collaborators and messages that changed. The agent renders the updated scene and diffs the previous revision against the new one, producing a visual diff plus a structural-diff bullet list for reviewers.
What the output includes
- A
diagramFamily: "sequence"scene with onesequence.actorper external initiator (the Client) and onesequence.lifelineper internal collaborator. - Messages typed correctly:
sequence.messagefor synchronous calls,sequence.replyfor return values (rendered with dashed open arrows),sequence.asyncfor fire-and-forget queue publishes (rendered with open arrowheads),sequence.createfor object instantiation in OO codebases. - Combined fragments with
extensions.operator: "alt" | "opt" | "loop" | "par"and operand dividers for branching paths - the canonical example here is the[charge succeeded]/[retry on 5xx]alt around the payment block. - Sequence notes anchored OVER a single lifeline (PlantUML / Mermaid convention) for inline implementation notes - visible in the diagram next to the message they describe.
- Self-messages rendered as rounded U-loops for handler-internal computations the agent thinks are worth surfacing (validation, response building).
- A revision diff showing exactly which lifelines, messages, fragments, or notes changed since the last run - the value-add over a one-shot sequence diagram.
What this example does not aim to do
This is not a tracing-driven recipe. It works from source code, not OpenTelemetry / Jaeger / Honeycomb spans. A trace-driven variant would identify the canonical request flow from real production traffic - useful for catching drift between the documented flow and what actually happens in production - but is a separate recipe with its own observability-stack dependencies. Build whichever fits your team; the source-code recipe is the lower-friction starting point.
Rendered diagram
Revision 2 as Zindex saved it, from the edit to revision 1 that Revision diff shows. Open the scene below in the Playground to swap themes (clean / dark / blueprint / sketch).
Scene JSON
Raw
The DSP scene of revision 2. Open it in the
Playground, or send it as scene to
POST /v1/diagrams/preview, to draw it from scratch.
{
"schemaVersion": "0.1",
"diagramFamily": "sequence",
"scene": {
"id": "request-flow-from-handler",
"title": "Checkout request flow",
"brief": "What happens when a client sends POST /checkout, traced from the handler: each service it calls, in order.\nOne lifeline per service the handler calls, messages in call order, each reply after its call. A retry is an alt fragment around the call it repeats. Update it when the handler's calls change.",
"units": "px",
"canvas": {
"width": 1900,
"height": 1150
}
},
"elements": [
{
"id": "client",
"kind": "node",
"nodeType": "sequence.actor",
"shape": "rect",
"label": "Client"
},
{
"id": "checkout",
"kind": "node",
"nodeType": "sequence.lifeline",
"shape": "rect",
"label": "Checkout Service"
},
{
"id": "auth",
"kind": "node",
"nodeType": "sequence.lifeline",
"shape": "rect",
"label": "Auth Service"
},
{
"id": "cache",
"kind": "node",
"nodeType": "sequence.lifeline",
"shape": "rect",
"label": "Redis Cache"
},
{
"id": "inventory",
"kind": "node",
"nodeType": "sequence.lifeline",
"shape": "rect",
"label": "Inventory Service"
},
{
"id": "payment",
"kind": "node",
"nodeType": "sequence.lifeline",
"shape": "rect",
"label": "Payment Provider\n(Stripe)"
},
{
"id": "notify",
"kind": "node",
"nodeType": "sequence.lifeline",
"shape": "rect",
"label": "Notification Queue"
},
{
"id": "m_post",
"kind": "edge",
"edgeType": "sequence.message",
"from": {
"elementId": "client"
},
"to": {
"elementId": "checkout"
},
"label": "POST /checkout"
},
{
"id": "m_verify",
"kind": "edge",
"edgeType": "sequence.message",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "auth"
},
"label": "verifyToken(jwt)"
},
{
"id": "m_verify_ok",
"kind": "edge",
"edgeType": "sequence.reply",
"from": {
"elementId": "auth"
},
"to": {
"elementId": "checkout"
},
"label": "user_id"
},
{
"id": "m_cache_get",
"kind": "edge",
"edgeType": "sequence.message",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "cache"
},
"label": "GET cart:{user_id}"
},
{
"id": "m_cache_hit",
"kind": "edge",
"edgeType": "sequence.reply",
"from": {
"elementId": "cache"
},
"to": {
"elementId": "checkout"
},
"label": "cart (hit)"
},
{
"id": "m_reserve",
"kind": "edge",
"edgeType": "sequence.message",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "inventory"
},
"label": "reserve(items)"
},
{
"id": "m_reserved",
"kind": "edge",
"edgeType": "sequence.reply",
"from": {
"elementId": "inventory"
},
"to": {
"elementId": "checkout"
},
"label": "reservation_id"
},
{
"id": "note_payment",
"kind": "node",
"nodeType": "sequence.note",
"shape": "rect",
"label": "Stripe charge with\nidempotency key",
"extensions": {
"anchor": "payment"
}
},
{
"id": "frag_charge",
"kind": "frame",
"containerType": "fragment",
"title": "[charge succeeded]",
"children": [
"m_charge",
"m_charge_ok",
"m_charge_retry",
"m_charge_retry_ok"
],
"extensions": {
"operator": "alt",
"operands": [
{
"startsAt": "m_charge_retry",
"guard": "retry on 5xx (exp backoff: 1s, 2s, 4s)"
}
]
}
},
{
"id": "m_charge",
"kind": "edge",
"edgeType": "sequence.message",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "payment"
},
"label": "charge($total, idempotency_key)"
},
{
"id": "m_charge_ok",
"kind": "edge",
"edgeType": "sequence.reply",
"from": {
"elementId": "payment"
},
"to": {
"elementId": "checkout"
},
"label": "charge_id"
},
{
"id": "m_charge_retry",
"kind": "edge",
"edgeType": "sequence.message",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "payment"
},
"label": "charge (retry)"
},
{
"id": "m_charge_retry_ok",
"kind": "edge",
"edgeType": "sequence.reply",
"from": {
"elementId": "payment"
},
"to": {
"elementId": "checkout"
},
"label": "charge_id (after retry)"
},
{
"id": "m_commit",
"kind": "edge",
"edgeType": "sequence.message",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "inventory"
},
"label": "commit(reservation_id)"
},
{
"id": "m_notify",
"kind": "edge",
"edgeType": "sequence.async",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "notify"
},
"label": "publish(order_placed)"
},
{
"id": "m_self_validate",
"kind": "edge",
"edgeType": "sequence.message",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "checkout"
},
"label": "build response"
},
{
"id": "m_response",
"kind": "edge",
"edgeType": "sequence.reply",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "client"
},
"label": "200 OK + receipt"
}
]
} Agent workflow
Build a sequence diagram of an HTTP endpoint's request flow by walking the handler's async/await chain and external integrations, then change the saved Zindex diagram with typed operations when a relevant code path changes.
Inputs
- Handler file path (e.g. apps/api/src/routes/checkout.ts) plus its directly-imported service modules
- Optional: monorepo paths to client SDK definitions for external integrations (Stripe, Twilio, etc.) so the agent emits accurate provider-side lifelines
- The diagram's Zindex key or ID
- A Zindex API key, or an MCP client signed in to Zindex
Outputs
- A new revision of the diagram with one lifeline per participant, one message per service interaction, and combined-fragment frames for branching paths
- Rendered SVG showing the canonical request flow at the current revision
- A compare listing added/removed lifelines, new fragments and changed messages (sync→async, etc.)
- A summary of the structural change with a link to the rendered SVG
- 01
Create or read the diagram
On the first run, save the parsed flow with
diagram_create, diagramFamily "sequence", akeysuch ascheckout-flowand abriefwhose first line says what the flow shows; Zindex mints the ID, and the brief's first line is what a search shows. On later runs, read the diagram by key to get the current revision and elements. - 02
Walk the handler's call graph
Parse the handler source file (TypeScript via the TS compiler API, Python via ast, Go via go/parser). Identify every awaited service call, queue publish, cache read/write, DB query, and external API request - each becomes a (caller, callee, operationName, kind) tuple. Distinguish synchronous calls (await response) from asynchronous publishes (fire-and-forget queue/topic). Branching constructs (try/catch with retry, if/else with parallel paths) become fragment metadata. Self-message candidates: handler-internal helpers that are visually meaningful (validation, response shaping).
- 03
Diff the parsed flow against the diagram
Read the diagram with
view: "dsp", since the outline doesn't show whether a message is synchronous or async. Compare parsed participants + messages + fragments against it. New participants → createNode with the participant type that fits (sequence.lifeline, sequence.actor, sequence.database, sequence.queue and the rest) andafternaming the participant to their left. New interactions → createEdge with appropriate edgeType andafternaming the message they follow. New branching paths → createFrame with containerType: "fragment" and the right operator (alt | opt | loop | par). Use stable element ids derived from service names so a renamed participant stays the same element. - 04
Save the changes as one edit
Send the diff as one
diagram_editwithbaseRevisionset to the revision you read and a meaningfulmessage(e.g. "add Redis cache layer; move notifications to async publish"). The edit is all or nothing. The agent uses stable lifeline ids (service.kebab-case) so a renamed service updates the existing lifeline rather than creating a duplicate. - 05
Fix what the warnings report
The edit's
warningslist the sequence rules the new revision breaks and what drawing it noticed, each with acode, theelementwhen there is one, and a one-linefix. A self-message such asm_self_validate, the handler's call to its own validation, is drawn as a loop and isn't warned. Fix what the list names with a follow-up edit. - 06
Render the new revision
Get SVG and PNG links to the new revision; they work without a key for 7 days. The image is drawn once and kept, and it prints its address,
zindex.ai/d/<id>@<revision>, and date, so it is traceable back to the saved diagram. - 07
Compare with the previous revision
Get a structural summary of what changed between PREV_REVISION and the new revision: added, changed and removed lifelines and messages. Drives the change summary.
- 08
Share the change summary
Share the structural summary and the rendered SVG with reviewers, for example as a pull-request comment. The reviewer sees what the new code does differently without reading the full code diff.
MCP recipe
For agents using Model Context Protocol. The tool sequence below matches the workflow steps; copy the prompt as a system message.
Tool sequence
- 01
diagram_createCreate or read the diagram - 02
diagram_getDiff the parsed flow against the diagram - 03
diagram_editSave the changes as one edit - 04
diagram_renderRender the new revision - 05
diagram_historyCompare with the previous revision
Unique tools used: diagram_create, diagram_get, diagram_edit, diagram_render, diagram_history.
Copyable agent prompt
Drop this verbatim into a system prompt for an MCP-connected agent.
The Zindex MCP server at https://api.zindex.ai/mcp exposes
the tools the prompt references (connect a client),
and so does the npm package @zindexai/mcp, which forwards
to it.
You maintain the sequence diagram of an HTTP endpoint's request flow that the team keeps in Zindex. When the handler changes, you parse its source and change the diagram with typed edits, each with a message saying what the code now does differently. Every revision is kept, so the team can open the request flow as it was on any date and compare two versions.
The diagram's Zindex ID is `${SCENE_ID}`; it already exists. Each update computes the smallest valid set of typed operations that move the diagram from its current revision to one that matches the current code.
Steps for each update:
1. Parse the handler source file at `${HANDLER_PATH}`. Walk the function's `async`/`await` chain (TypeScript via the TS compiler API, Python via `ast`, Go via `go/parser`). For each awaited call, identify the callee (service / collaborator) and the kind: synchronous (the handler waits on a response - emit `sequence.message` + `sequence.reply`), asynchronous (the handler does not await a response - emit `sequence.async`), or self-handler (an internal helper worth surfacing - emit a self-`sequence.message` from the handler back to itself).
2. Identify branching paths. A `try { primary() } catch { retry() }` becomes an `alt` fragment with two operands ("primary" / "retry"). An `if (cond) { sometimes() }` becomes an `opt` fragment. A `for (item of items) { process(item) }` becomes a `loop` fragment. `Promise.all([a(), b()])` becomes a `par` fragment.
3. Annotate non-obvious behavior with `sequence.note` nodes anchored OVER the relevant lifeline. Idempotency keys, retry budgets, timeouts, side-effect ordering - anything a future engineer would want to read alongside the code. Notes are NOT a substitute for code comments; use them for structural facts the diagram alone wouldn't convey.
4. Call `diagram_get({ id: "${SCENE_ID}", view: "dsp" })` to read the current revision and the scene JSON; the default outline doesn't show whether a message is synchronous or async. Diff what you parsed against it: new lifelines → `createNode` with `after` naming the lifeline to its left, removed lifelines → `deleteElement`, new messages and notes → `createEdge` or `createNode` with `after` naming the message they follow (without it, they're added at the end), message-kind changes (sync → async) → `updateEdge`, a message that now happens earlier or later → `updateEdge` with `after` or `before`. To add a message after a fragment rather than as its last message, name the fragment. A fragment's operands start at a message (`operands: [{ startsAt, guard }]`) and move with it; a message added `before` an operand's first message becomes its first. Keep stable lifeline ids (kebab-case service name) so renames update the existing lifeline rather than producing a delete + create.
5. Call `diagram_edit({ id: "${SCENE_ID}", baseRevision, message, ops })` with one batch, `baseRevision` set to the revision you read. The edit is all or nothing. Pass a meaningful `message` like "add Redis cache layer; move notifications to async publish" - this surfaces in the revision history. If the call returns `REVISION_CONFLICT`, the diagram changed after you read it: the error lists what changed, so re-plan against the new revision.
6. An edit with errors returns `VALIDATION_FAILED` and saves nothing. A saved edit returns `warnings`: the sequence rules the new revision breaks and what drawing it noticed, each with a `code`, the `element` when there is one, and a one-line `fix`. `LABEL_DUPLICATION_DETECTED` deserves a look: sequence diagrams allow same-label messages at different times, but a duplicate at the same source is usually mis-typed. Fix the rest with a follow-up edit.
7. Call `diagram_render({ id: "${SCENE_ID}" })`. It returns SVG and PNG links to the new revision, valid for 7 days. Download the SVG and publish it to the docs site (or commit it to `docs/architecture/${ENDPOINT}-flow.svg`). The image prints its address, `zindex.ai/d/<id>@<revision>`, and date, so the published image is traceable.
8. Call `diagram_history({ id: "${SCENE_ID}", compare: { from: PREV_REVISION } })`. Share a short summary of the result with the people reviewing the code change: which lifelines were added/removed, which messages changed kind, which fragments were introduced. Reviewers see what the new code does differently before reading the code diff.
Hard rules: never hand-edit the rendered SVG; always edit the diagram with `diagram_edit` and render again. Never recreate the diagram from scratch on each update; always patch with stable ids - the request flow is a long-lived, evolving graph and stable ids are what make revision history meaningful. Treat the handler source as the source of truth; if a comment in the code contradicts the actual call, follow the actual call.
HTTP API recipe
For agents/devs not using MCP. Send
Authorization: Bearer $ZINDEX_API_KEY on every call
except POST /v1/diagrams/validate and
POST /v1/diagrams/preview, which need no key. In the
paths, ${SCENE_ID} is the diagram's ID, or the
key you gave it in diagram_create. Full
reference: REST API, OpenAPI spec.
- 01
POST/v1/diagramsOn the first run, save the parsed flow with
diagram_create, diagramFamily "sequence", akeysuch ascheckout-flowand abriefwhose first line says what the flow shows; Zindex mints the ID, and the brief's first line is what a search shows. On later runs, read the diagram by key to get the current revision and elements.Example response
{ "id": "dgm_xj3kdGj3xfd7", "key": "checkout-flow", "revision": 1, "hash": "sha256:6c366ac1baa93f14dc573a9a3a73ecaa6596c1a541933964e73f42ec2612009c", "chain": "sha256:75b9757a896f427e5b5ac3a0512a41ce8114e390688fc106b62968991cf908d1", "warnings": [], "created": true } - 02
GET/v1/diagrams/${SCENE_ID}?view=dspRead the diagram with
view: "dsp", since the outline doesn't show whether a message is synchronous or async. Compare parsed participants + messages + fragments against it. New participants → createNode with the participant type that fits (sequence.lifeline, sequence.actor, sequence.database, sequence.queue and the rest) andafternaming the participant to their left. New interactions → createEdge with appropriate edgeType andafternaming the message they follow. New branching paths → createFrame with containerType: "fragment" and the right operator (alt | opt | loop | par). Use stable element ids derived from service names so a renamed participant stays the same element.Example response
{ "id": "dgm_xj3kdGj3xfd7", "key": "checkout-flow", "revision": 1, "hash": "sha256:6c366ac1baa93f14dc573a9a3a73ecaa6596c1a541933964e73f42ec2612009c", "chain": "sha256:75b9757a896f427e5b5ac3a0512a41ce8114e390688fc106b62968991cf908d1", "createdAt": "2026-11-09T23:47:24.025Z", "visibility": "private", "scene": { "schemaVersion": "0.1", "diagramFamily": "sequence", "scene": { "id": "dgm_xj3kdGj3xfd7", "title": "Checkout request flow", "...": "..." }, "elements": [ { "id": "client", "kind": "node", "nodeType": "sequence.actor", "label": "Client", "...": "..." }, "..." ], "...": "..." } } - 03
POST/v1/diagrams/${SCENE_ID}/revisionsSend the diff as one
diagram_editwithbaseRevisionset to the revision you read and a meaningfulmessage(e.g. "add Redis cache layer; move notifications to async publish"). The edit is all or nothing. The agent uses stable lifeline ids (service.kebab-case) so a renamed service updates the existing lifeline rather than creating a duplicate.Example response
{ "id": "dgm_xj3kdGj3xfd7", "revision": 2, "hash": "sha256:fd4d2b2e1ff533bcaa4e74a19d16e8f13a687737b46426efffeb2402351bdc11", "chain": "sha256:3fb1de4953e16976bcab585313faa8d4f5d8ad65d029abc03280ca563cae7016", "warnings": [], "changed": { "added": [ "cache", "m_cache_get", "m_cache_hit", "note_payment", "m_charge_retry", "m_charge_retry_ok", "m_self_validate", "frag_charge" ], "updated": [ "notify", "m_charge", "m_notify" ], "removed": [ "cart", "m_cart_get", "m_cart_data", "m_notify_ok" ] } } - 04
GET/v1/diagrams/${SCENE_ID}/renderGet SVG and PNG links to the new revision; they work without a key for 7 days. The image is drawn once and kept, and it prints its address,
zindex.ai/d/<id>@<revision>, and date, so it is traceable back to the saved diagram.Example response
{ "id": "dgm_xj3kdGj3xfd7", "title": "Checkout request flow", "revision": 2, "latest": 2, "savedAt": "2026-11-09T23:47:24.110Z", "hash": "sha256:fd4d2b2e1ff533bcaa4e74a19d16e8f13a687737b46426efffeb2402351bdc11", "chain": "sha256:3fb1de4953e16976bcab585313faa8d4f5d8ad65d029abc03280ca563cae7016", "engine": "8.33.1+build.3683", "svg": "https://api.zindex.ai/v1/images/dgm_xj3kdGj3xfd7@2.svg?e=1794872844&s=...", "png": "https://api.zindex.ai/v1/images/dgm_xj3kdGj3xfd7@2.png?e=1794872844&s=...", "expires": "2026-11-16T23:47:24.000Z", "width": 1900, "height": 1260 } - 05
GET/v1/diagrams/${SCENE_ID}/compare?from=${PREV_REVISION}&to=${NEW_REVISION}Get a structural summary of what changed between PREV_REVISION and the new revision: added, changed and removed lifelines and messages. Drives the change summary.
Example response
{ "id": "dgm_xj3kdGj3xfd7", "from": 1, "to": 2, "added": [ "cache", "m_cache_get", "m_cache_hit", "note_payment", "m_charge_retry", "m_charge_retry_ok", "m_self_validate", "frag_charge" ], "changed": [ "notify", "m_charge", "m_notify" ], "removed": [ "cart", "m_cart_get", "m_cart_data", "m_notify_ok" ], "scene": [ "canvas" ], "authors": [ { "by": null, "client": "curl/8.7.1" } ] }
Operations
Raw The typed operations that build revision 2's scene from empty in one edit, not through the edit the diagram above was saved by. Save an
empty diagram with diagram_create, then send the
envelope's baseRevision, message and
ops to diagram_edit, or
POST /v1/diagrams/{id}/revisions. Each op
carries a stable id so subsequent runs can update the
same elements instead of regenerating.
{
"schemaVersion": "0.1",
"sceneId": "request-flow-from-handler",
"baseRevision": 1,
"message": "Build /checkout request-flow scene: 8 lifelines, alt fragment around payment retry, async notification publish",
"ops": [
{
"op": "createNode",
"id": "client",
"nodeType": "sequence.actor",
"shape": "rect",
"label": "Client"
},
{
"op": "createNode",
"id": "checkout",
"nodeType": "sequence.lifeline",
"shape": "rect",
"label": "Checkout Service"
},
{
"op": "createNode",
"id": "auth",
"nodeType": "sequence.lifeline",
"shape": "rect",
"label": "Auth Service"
},
{
"op": "createNode",
"id": "cache",
"nodeType": "sequence.lifeline",
"shape": "rect",
"label": "Redis Cache"
},
{
"op": "createNode",
"id": "inventory",
"nodeType": "sequence.lifeline",
"shape": "rect",
"label": "Inventory Service"
},
{
"op": "createNode",
"id": "payment",
"nodeType": "sequence.lifeline",
"shape": "rect",
"label": "Payment Provider\n(Stripe)"
},
{
"op": "createNode",
"id": "notify",
"nodeType": "sequence.lifeline",
"shape": "rect",
"label": "Notification Queue"
},
{
"op": "createEdge",
"id": "m_post",
"edgeType": "sequence.message",
"from": {
"elementId": "client"
},
"to": {
"elementId": "checkout"
},
"label": "POST /checkout"
},
{
"op": "createEdge",
"id": "m_verify",
"edgeType": "sequence.message",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "auth"
},
"label": "verifyToken(jwt)"
},
{
"op": "createEdge",
"id": "m_verify_ok",
"edgeType": "sequence.reply",
"from": {
"elementId": "auth"
},
"to": {
"elementId": "checkout"
},
"label": "user_id"
},
{
"op": "createEdge",
"id": "m_cache_get",
"edgeType": "sequence.message",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "cache"
},
"label": "GET cart:{user_id}"
},
{
"op": "createEdge",
"id": "m_cache_hit",
"edgeType": "sequence.reply",
"from": {
"elementId": "cache"
},
"to": {
"elementId": "checkout"
},
"label": "cart (hit)"
},
{
"op": "createEdge",
"id": "m_reserve",
"edgeType": "sequence.message",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "inventory"
},
"label": "reserve(items)"
},
{
"op": "createEdge",
"id": "m_reserved",
"edgeType": "sequence.reply",
"from": {
"elementId": "inventory"
},
"to": {
"elementId": "checkout"
},
"label": "reservation_id"
},
{
"op": "createNode",
"id": "note_payment",
"nodeType": "sequence.note",
"shape": "rect",
"label": "Stripe charge with\nidempotency key",
"extensions": {
"anchor": "payment"
}
},
{
"op": "createEdge",
"id": "m_charge",
"edgeType": "sequence.message",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "payment"
},
"label": "charge($total, idempotency_key)"
},
{
"op": "createEdge",
"id": "m_charge_ok",
"edgeType": "sequence.reply",
"from": {
"elementId": "payment"
},
"to": {
"elementId": "checkout"
},
"label": "charge_id"
},
{
"op": "createEdge",
"id": "m_charge_retry",
"edgeType": "sequence.message",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "payment"
},
"label": "charge (retry)"
},
{
"op": "createEdge",
"id": "m_charge_retry_ok",
"edgeType": "sequence.reply",
"from": {
"elementId": "payment"
},
"to": {
"elementId": "checkout"
},
"label": "charge_id (after retry)"
},
{
"op": "createFrame",
"id": "frag_charge",
"containerType": "fragment",
"title": "[charge succeeded]",
"children": [
"m_charge",
"m_charge_ok",
"m_charge_retry",
"m_charge_retry_ok"
],
"extensions": {
"operator": "alt",
"operands": [
{
"startsAt": "m_charge_retry",
"guard": "retry on 5xx (exp backoff: 1s, 2s, 4s)"
}
]
}
},
{
"op": "createEdge",
"id": "m_commit",
"edgeType": "sequence.message",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "inventory"
},
"label": "commit(reservation_id)"
},
{
"op": "createEdge",
"id": "m_notify",
"edgeType": "sequence.async",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "notify"
},
"label": "publish(order_placed)"
},
{
"op": "createEdge",
"id": "m_self_validate",
"edgeType": "sequence.message",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "checkout"
},
"label": "build response"
},
{
"op": "createEdge",
"id": "m_response",
"edgeType": "sequence.reply",
"from": {
"elementId": "checkout"
},
"to": {
"elementId": "client"
},
"label": "200 OK + receipt"
}
]
} Validation
Valid
Captured response from POST /v1/diagrams/validate, the
check diagram_validate runs. It checks the scene and
draws it. Every code it can return is in the validation rules.
- 0 errors
- 0 warnings
The scene validates with no errors or warnings.
Each entry has a code, the element it
concerns when there is one, and a one-line fix.
diagram_create and diagram_edit save
nothing when there are errors and return
VALIDATION_FAILED; warnings don't block a save. Both
return the same warnings for the revision they save, so an agent
reads them from the write itself.
Revision diff
Raw
What changed between two revisions of the diagram, as
diagram_history returns it with compare.
Every revision is kept, so any two can be compared, by revision
number or by date.
Scenario
The 'Improve checkout latency' change lands. The handler reads the cart from a Redis cache instead of calling the cart service, retries a failed Stripe charge inside an alt fragment, and publishes the order email to a queue instead of calling the notification service and waiting. Eight elements are new: the cache lifeline and its two messages, a note on the idempotency key, the retry fragment and its two messages, and a self-message for building the response. Four are gone: the cart lifeline, its two messages and the notification reply. Three changed: the notification lifeline is now a queue, the charge call carries an idempotency key, and m_notify is an async publish. The canvas grew to fit, so scene lists canvas. Reviewers read this list next to the before and after diagrams before they read the code.
- Revision 1 → 2
- +8 added
- -4 removed
- ~3 changed
- scene fields changed: canvas
+ Added
cachem_cache_getm_cache_hitnote_paymentm_charge_retrym_charge_retry_okm_self_validatefrag_charge
− Removed
cartm_cart_getm_cart_datam_notify_ok
~ Changed
notifym_chargem_notify
Raw compare response
{
"id": "dgm_cVEsZwKBqLQ3",
"from": 1,
"to": 2,
"added": [
"cache",
"m_cache_get",
"m_cache_hit",
"note_payment",
"m_charge_retry",
"m_charge_retry_ok",
"m_self_validate",
"frag_charge"
],
"changed": [
"notify",
"m_charge",
"m_notify"
],
"removed": [
"cart",
"m_cart_get",
"m_cart_data",
"m_notify_ok"
],
"scene": [
"canvas"
],
"scenario": "The 'Improve checkout latency' change lands. The handler reads the cart from a Redis cache instead of calling the cart service, retries a failed Stripe charge inside an alt fragment, and publishes the order email to a queue instead of calling the notification service and waiting. Eight elements are new: the cache lifeline and its two messages, a note on the idempotency key, the retry fragment and its two messages, and a self-message for building the response. Four are gone: the cart lifeline, its two messages and the notification reply. Three changed: the notification lifeline is now a queue, the charge call carries an idempotency key, and m_notify is an async publish. The canvas grew to fit, so scene lists canvas. Reviewers read this list next to the before and after diagrams before they read the code."
} Agent resources
Machine-readable versions of this example. Agents should fetch these rather than scrape the rendered HTML.
-
request-flow-from-handler.scene.jsonCanonical DSP scene Open -
request-flow-from-handler.ops.jsonTyped-operation envelope that builds the scene Open -
request-flow-from-handler.workflow.jsonStructured agent workflow (goal, inputs, outputs, steps) Open -
request-flow-from-handler.diff.jsonSamplediagram_historycompare response Open -
request-flow-from-handler.svgRendered diagram: revision 2 as Zindex saved it Open -
request-flow-from-handler.before.svgRevision diff's before picture: revision 1 as Zindex saved it Open -
request-flow-from-handler.mdAgent-readable markdown summary Open -
/examples/index.jsonManifest of all examples (cross-linked) Open