New Bring your own storage. Keep your diagrams in your own private GitHub repository, on Pro and Team.Bring your own storage on GitHub, for Pro and Team. Learn more about bring your own storage

All examples

Request flow diagram from handler code

A sequence diagram of your flagship endpoint's request lifecycle. The agent walks the handler's async/await calls and external integrations, then records each code change as a new revision with a structural diff.

sequence Handler source code (TypeScript / Python / Go) scangenerateupdate

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 one sequence.actor per external initiator (the Client) and one sequence.lifeline per internal collaborator.
  • Messages typed correctly: sequence.message for synchronous calls, sequence.reply for return values (rendered with dashed open arrows), sequence.async for fire-and-forget queue publishes (rendered with open arrowheads), sequence.create for 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

Request flow diagram from handler code - revision 2

Open full size

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
  1. 01

    Create or read the diagram

    On the first run, save the parsed flow with diagram_create, diagramFamily "sequence", a key such as checkout-flow and a brief whose 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.

    diagram_create POST /v1/diagrams
  2. 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).

  3. 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) and after naming the participant to their left. New interactions → createEdge with appropriate edgeType and after naming 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.

    diagram_get GET /v1/diagrams/${SCENE_ID}?view=dsp
  4. 04

    Save the changes as one edit

    Send the diff as one diagram_edit with baseRevision set to the revision you read and a meaningful message (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.

    diagram_edit POST /v1/diagrams/${SCENE_ID}/revisions
  5. 05

    Fix what the warnings report

    The edit's warnings list 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. A self-message such as m_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.

  6. 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.

    diagram_render GET /v1/diagrams/${SCENE_ID}/render
  7. 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.

    diagram_history GET /v1/diagrams/${SCENE_ID}/compare?from=${PREV_REVISION}&to=${NEW_REVISION}
  8. 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

  1. 01 diagram_create Create or read the diagram
  2. 02 diagram_get Diff the parsed flow against the diagram
  3. 03 diagram_edit Save the changes as one edit
  4. 04 diagram_render Render the new revision
  5. 05 diagram_history Compare 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.

  1. 01 POST /v1/diagrams

    On the first run, save the parsed flow with diagram_create, diagramFamily "sequence", a key such as checkout-flow and a brief whose 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
    }
  2. 02 GET /v1/diagrams/${SCENE_ID}?view=dsp

    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) and after naming the participant to their left. New interactions → createEdge with appropriate edgeType and after naming 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",
            "...": "..."
          },
          "..."
        ],
        "...": "..."
      }
    }
  3. 03 POST /v1/diagrams/${SCENE_ID}/revisions

    Send the diff as one diagram_edit with baseRevision set to the revision you read and a meaningful message (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"
        ]
      }
    }
  4. 04 GET /v1/diagrams/${SCENE_ID}/render

    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.

    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
    }
  5. 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.

  • 24 operations
  • 15 createEdge, 1 createFrame, 8 createNode
{
  "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
Before · revision 1
Request flow diagram from handler code - revision 1

Open full size of revision 1

After · revision 2
Request flow diagram from handler code - revision 2

Open full size of revision 2

+ Added

  • cache
  • m_cache_get
  • m_cache_hit
  • note_payment
  • m_charge_retry
  • m_charge_retry_ok
  • m_self_validate
  • frag_charge

− Removed

  • cart
  • m_cart_get
  • m_cart_data
  • m_notify_ok

~ Changed

  • notify
  • m_charge
  • m_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.json Canonical DSP scene Open
  • request-flow-from-handler.ops.json Typed-operation envelope that builds the scene Open
  • request-flow-from-handler.workflow.json Structured agent workflow (goal, inputs, outputs, steps) Open
  • request-flow-from-handler.diff.json Sample diagram_history compare response Open
  • request-flow-from-handler.svg Rendered diagram: revision 2 as Zindex saved it Open
  • request-flow-from-handler.before.svg Revision diff's before picture: revision 1 as Zindex saved it Open
  • request-flow-from-handler.md Agent-readable markdown summary Open
  • /examples/index.json Manifest of all examples (cross-linked) Open