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

Living architecture diagram from a repository scan

Let an agent scan a repository and build a frame-grouped service architecture diagram: services, databases, queues, and external systems with edge labels. Later scans patch the same scene with typed operations.

architecture Codebase / configuration files scangenerateupdate

What this example shows

A modern SaaS platform rendered as a frame-grouped architecture diagram - clients, edge, API layer, services, async, data plane, observability, and external systems each visually separated with labeled edges showing the dependencies between them. When a service is added, the agent patches the same scene instead of regenerating a one-shot artwork.

When to use it

When your architecture documentation matters but no one wants to redraw it by hand. The agent reads source code, configuration, and infrastructure-as-code; identifies services, databases, queues, and external systems; and applies typed operations to a persisted diagram. Each run adds a revision, so the history shows how the architecture changed from one run to the next.

What the agent does

The agent scans the repository and identifies the components: services from package.json workspaces, databases from connection strings or ORM configs, queues from worker definitions, external systems from outbound HTTP / SDK imports. It fetches the persisted scene, applies createNode for new components, updateNode when properties change, createEdge for new dependencies, and deleteElement for removed components. Then it validates structurally, renders the result, and stores the new revision.

Because element IDs stay stable across runs, frame groupings stay intact and a small change produces a small revision diff. New engineers see the current architecture; reviewers see exactly what each revision added or removed.

What the output includes

  • A frame-grouped architecture diagram with seven logical layers (clients, edge, API, services, async, data plane, observability) plus an external-systems sidebar.
  • Lucide icons on every component for quick visual recognition.
  • Edge labels showing the protocol or relationship (HTTPS, queries, publishes, charges, emails).
  • Dashed edges for asynchronous flows; solid for synchronous request/response.
  • Frame-level edges (e.g. services → observability) to express “the whole layer emits telemetry” without drawing N redundant arrows.
  • An explicit layout on every node and frame, because the tiers are an arrangement by meaning that the layout engine can’t infer from the edges. A tier frame keeps its box, and a new component goes inside its tier where there is room; when there isn’t, the edit warns NODE_OUTSIDE_FRAME. The agent sends autoLayout only with elements: without them, it drops the eight tier frames’ layout and lays every node out again by its edges: each tier stays round its members, but the arrangement of the tiers is lost.

Rendered diagram

Living architecture diagram from a repository scan - rendered diagram

Open full size

Drawn by Zindex from the scene below with POST /v1/diagrams/preview. Open it in the Playground to swap themes (clean / dark / blueprint / sketch), or add format: "png" to the same request for a PNG.

Scene JSON

Raw

The DSP scene the diagram above is drawn from. Open it in the Playground, or send it as scene to POST /v1/diagrams/preview to draw it yourself.

{
  "schemaVersion": "0.1",
  "diagramFamily": "architecture",
  "scene": {
    "id": "saas-platform",
    "title": "Modern SaaS Platform",
    "brief": "The SaaS platform's architecture by tier: clients, edge, API, services, async jobs, data, observability and providers.\nGenerated from the repository by detectors, and changed with edits when asked. Each tier is a dashed frame; keep every component in its tier's frame.",
    "units": "px",
    "canvas": {
      "width": 1400,
      "height": 1200
    }
  },
  "elements": [
    {
      "id": "clients",
      "kind": "frame",
      "title": "Clients",
      "containerType": "generic",
      "style": {
        "fill": "rgba(255, 255, 255, 0.5)",
        "dash": [
          4,
          4
        ],
        "cornerRadius": 8
      },
      "layout": {
        "mode": "absolute",
        "x": 40,
        "y": 30,
        "width": 1080,
        "height": 170
      },
      "children": [
        "web",
        "mobile",
        "api_consumer"
      ]
    },
    {
      "id": "web",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Web App",
      "icon": "lucide:monitor",
      "layout": {
        "mode": "absolute",
        "x": 230,
        "y": 75,
        "width": 180,
        "height": 110
      }
    },
    {
      "id": "mobile",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Mobile App",
      "icon": "lucide:smartphone",
      "layout": {
        "mode": "absolute",
        "x": 490,
        "y": 75,
        "width": 180,
        "height": 110
      }
    },
    {
      "id": "api_consumer",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Public API",
      "icon": "lucide:code",
      "layout": {
        "mode": "absolute",
        "x": 750,
        "y": 75,
        "width": 180,
        "height": 110
      }
    },
    {
      "id": "edge",
      "kind": "frame",
      "title": "Edge",
      "containerType": "generic",
      "style": {
        "fill": "rgba(255, 255, 255, 0.5)",
        "dash": [
          4,
          4
        ],
        "cornerRadius": 8
      },
      "layout": {
        "mode": "absolute",
        "x": 40,
        "y": 220,
        "width": 1080,
        "height": 170
      },
      "children": [
        "cdn",
        "waf"
      ]
    },
    {
      "id": "cdn",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "CDN",
      "icon": "lucide:globe",
      "layout": {
        "mode": "absolute",
        "x": 330,
        "y": 265,
        "width": 200,
        "height": 110
      }
    },
    {
      "id": "waf",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "WAF",
      "icon": "lucide:shield",
      "layout": {
        "mode": "absolute",
        "x": 630,
        "y": 265,
        "width": 200,
        "height": 110
      }
    },
    {
      "id": "api",
      "kind": "frame",
      "title": "API Layer",
      "containerType": "generic",
      "style": {
        "fill": "rgba(255, 255, 255, 0.5)",
        "dash": [
          4,
          4
        ],
        "cornerRadius": 8
      },
      "layout": {
        "mode": "absolute",
        "x": 40,
        "y": 410,
        "width": 1080,
        "height": 170
      },
      "children": [
        "gateway",
        "auth"
      ]
    },
    {
      "id": "gateway",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "API Gateway",
      "icon": "lucide:network",
      "layout": {
        "mode": "absolute",
        "x": 330,
        "y": 455,
        "width": 200,
        "height": 110
      }
    },
    {
      "id": "auth",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Auth Service",
      "icon": "lucide:lock",
      "layout": {
        "mode": "absolute",
        "x": 630,
        "y": 455,
        "width": 200,
        "height": 110
      }
    },
    {
      "id": "services",
      "kind": "frame",
      "title": "Services",
      "containerType": "generic",
      "style": {
        "fill": "rgba(255, 255, 255, 0.5)",
        "dash": [
          4,
          4
        ],
        "cornerRadius": 8
      },
      "layout": {
        "mode": "absolute",
        "x": 40,
        "y": 600,
        "width": 1080,
        "height": 170
      },
      "children": [
        "users",
        "catalog",
        "orders",
        "payments",
        "notifs"
      ]
    },
    {
      "id": "users",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Users",
      "icon": "lucide:users",
      "layout": {
        "mode": "absolute",
        "x": 110,
        "y": 645,
        "width": 140,
        "height": 110
      }
    },
    {
      "id": "catalog",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Catalog",
      "icon": "lucide:boxes",
      "layout": {
        "mode": "absolute",
        "x": 310,
        "y": 645,
        "width": 140,
        "height": 110
      }
    },
    {
      "id": "orders",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Orders",
      "icon": "lucide:package",
      "layout": {
        "mode": "absolute",
        "x": 510,
        "y": 645,
        "width": 140,
        "height": 110
      }
    },
    {
      "id": "payments",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Payments",
      "icon": "lucide:layers",
      "layout": {
        "mode": "absolute",
        "x": 710,
        "y": 645,
        "width": 140,
        "height": 110
      }
    },
    {
      "id": "notifs",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Notifications",
      "icon": "lucide:bell",
      "layout": {
        "mode": "absolute",
        "x": 910,
        "y": 645,
        "width": 140,
        "height": 110
      }
    },
    {
      "id": "async",
      "kind": "frame",
      "title": "Async",
      "containerType": "generic",
      "style": {
        "fill": "rgba(255, 255, 255, 0.5)",
        "dash": [
          4,
          4
        ],
        "cornerRadius": 8
      },
      "layout": {
        "mode": "absolute",
        "x": 40,
        "y": 790,
        "width": 1080,
        "height": 170
      },
      "children": [
        "event_bus",
        "workers",
        "scheduler"
      ]
    },
    {
      "id": "event_bus",
      "kind": "node",
      "nodeType": "queue",
      "shape": "roundedRect",
      "label": "Event Bus",
      "icon": "lucide:zap",
      "layout": {
        "mode": "absolute",
        "x": 230,
        "y": 835,
        "width": 180,
        "height": 110
      }
    },
    {
      "id": "workers",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Workers",
      "icon": "lucide:cpu",
      "layout": {
        "mode": "absolute",
        "x": 490,
        "y": 835,
        "width": 180,
        "height": 110
      }
    },
    {
      "id": "scheduler",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Scheduler",
      "icon": "lucide:clock",
      "layout": {
        "mode": "absolute",
        "x": 750,
        "y": 835,
        "width": 180,
        "height": 110
      }
    },
    {
      "id": "data",
      "kind": "frame",
      "title": "Data Plane",
      "containerType": "generic",
      "style": {
        "fill": "rgba(255, 255, 255, 0.5)",
        "dash": [
          4,
          4
        ],
        "cornerRadius": 8
      },
      "layout": {
        "mode": "absolute",
        "x": 40,
        "y": 980,
        "width": 1080,
        "height": 170
      },
      "children": [
        "postgres",
        "redis",
        "search",
        "storage"
      ]
    },
    {
      "id": "postgres",
      "kind": "node",
      "nodeType": "database",
      "shape": "cylinder",
      "label": "PostgreSQL",
      "icon": "lucide:database",
      "layout": {
        "mode": "absolute",
        "x": 170,
        "y": 1010,
        "width": 160,
        "height": 130
      }
    },
    {
      "id": "redis",
      "kind": "node",
      "nodeType": "database",
      "shape": "cylinder",
      "label": "Redis",
      "icon": "lucide:database",
      "layout": {
        "mode": "absolute",
        "x": 390,
        "y": 1010,
        "width": 160,
        "height": 130
      }
    },
    {
      "id": "search",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Search Index",
      "icon": "lucide:search",
      "layout": {
        "mode": "absolute",
        "x": 610,
        "y": 1025,
        "width": 160,
        "height": 110
      }
    },
    {
      "id": "storage",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Object Storage",
      "icon": "lucide:hard-drive",
      "layout": {
        "mode": "absolute",
        "x": 830,
        "y": 1025,
        "width": 160,
        "height": 110
      }
    },
    {
      "id": "observability",
      "kind": "frame",
      "title": "Observability",
      "containerType": "generic",
      "style": {
        "fill": "rgba(255, 255, 255, 0.5)",
        "dash": [
          4,
          4
        ],
        "cornerRadius": 8
      },
      "layout": {
        "mode": "absolute",
        "x": 1160,
        "y": 30,
        "width": 220,
        "height": 550
      },
      "children": [
        "logs",
        "metrics",
        "tracing"
      ]
    },
    {
      "id": "logs",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Logs",
      "icon": "lucide:terminal",
      "layout": {
        "mode": "absolute",
        "x": 1190,
        "y": 90,
        "width": 160,
        "height": 110
      }
    },
    {
      "id": "metrics",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Metrics",
      "icon": "lucide:bar-chart",
      "layout": {
        "mode": "absolute",
        "x": 1190,
        "y": 240,
        "width": 160,
        "height": 110
      }
    },
    {
      "id": "tracing",
      "kind": "node",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Tracing",
      "icon": "lucide:activity",
      "layout": {
        "mode": "absolute",
        "x": 1190,
        "y": 390,
        "width": 160,
        "height": 110
      }
    },
    {
      "id": "external",
      "kind": "frame",
      "title": "External",
      "containerType": "generic",
      "style": {
        "fill": "rgba(255, 255, 255, 0.5)",
        "dash": [
          4,
          4
        ],
        "cornerRadius": 8
      },
      "layout": {
        "mode": "absolute",
        "x": 1160,
        "y": 600,
        "width": 220,
        "height": 540
      },
      "children": [
        "stripe",
        "sendgrid"
      ]
    },
    {
      "id": "stripe",
      "kind": "node",
      "nodeType": "externalSystem",
      "shape": "roundedRect",
      "label": "Payment\nProvider",
      "icon": "lucide:external-link",
      "layout": {
        "mode": "absolute",
        "x": 1190,
        "y": 700,
        "width": 160,
        "height": 110
      }
    },
    {
      "id": "sendgrid",
      "kind": "node",
      "nodeType": "externalSystem",
      "shape": "roundedRect",
      "label": "Email\nProvider",
      "icon": "lucide:mail",
      "layout": {
        "mode": "absolute",
        "x": 1190,
        "y": 880,
        "width": 160,
        "height": 110
      }
    },
    {
      "id": "e_web_cdn",
      "kind": "edge",
      "from": {
        "elementId": "web"
      },
      "to": {
        "elementId": "cdn"
      },
      "label": "HTTPS",
      "router": "orthogonal"
    },
    {
      "id": "e_mob_cdn",
      "kind": "edge",
      "from": {
        "elementId": "mobile"
      },
      "to": {
        "elementId": "cdn"
      },
      "label": "HTTPS",
      "router": "orthogonal"
    },
    {
      "id": "e_api_cdn",
      "kind": "edge",
      "from": {
        "elementId": "api_consumer"
      },
      "to": {
        "elementId": "cdn"
      },
      "label": "HTTPS",
      "router": "orthogonal"
    },
    {
      "id": "e_cdn_waf",
      "kind": "edge",
      "from": {
        "elementId": "cdn"
      },
      "to": {
        "elementId": "waf"
      },
      "router": "orthogonal"
    },
    {
      "id": "e_waf_gw",
      "kind": "edge",
      "from": {
        "elementId": "waf"
      },
      "to": {
        "elementId": "gateway"
      },
      "router": "orthogonal"
    },
    {
      "id": "e_gw_auth",
      "kind": "edge",
      "from": {
        "elementId": "gateway"
      },
      "to": {
        "elementId": "auth"
      },
      "label": "validates",
      "router": "orthogonal"
    },
    {
      "id": "e_gw_users",
      "kind": "edge",
      "from": {
        "elementId": "gateway"
      },
      "to": {
        "elementId": "users"
      },
      "router": "orthogonal"
    },
    {
      "id": "e_gw_catalog",
      "kind": "edge",
      "from": {
        "elementId": "gateway"
      },
      "to": {
        "elementId": "catalog"
      },
      "router": "orthogonal"
    },
    {
      "id": "e_gw_orders",
      "kind": "edge",
      "from": {
        "elementId": "gateway"
      },
      "to": {
        "elementId": "orders"
      },
      "router": "orthogonal"
    },
    {
      "id": "e_orders_payments",
      "kind": "edge",
      "from": {
        "elementId": "orders"
      },
      "to": {
        "elementId": "payments"
      },
      "label": "triggers",
      "router": "orthogonal"
    },
    {
      "id": "e_users_db",
      "kind": "edge",
      "from": {
        "elementId": "users"
      },
      "to": {
        "elementId": "postgres"
      },
      "label": "queries",
      "router": "orthogonal"
    },
    {
      "id": "e_catalog_search",
      "kind": "edge",
      "from": {
        "elementId": "catalog"
      },
      "to": {
        "elementId": "search"
      },
      "label": "indexes",
      "router": "orthogonal"
    },
    {
      "id": "e_orders_db",
      "kind": "edge",
      "from": {
        "elementId": "orders"
      },
      "to": {
        "elementId": "postgres"
      },
      "router": "orthogonal"
    },
    {
      "id": "e_orders_redis",
      "kind": "edge",
      "from": {
        "elementId": "orders"
      },
      "to": {
        "elementId": "redis"
      },
      "label": "cache",
      "router": "orthogonal"
    },
    {
      "id": "e_orders_evt",
      "kind": "edge",
      "from": {
        "elementId": "orders"
      },
      "to": {
        "elementId": "event_bus"
      },
      "label": "publishes",
      "router": "orthogonal",
      "style": {
        "dash": [
          4,
          4
        ]
      }
    },
    {
      "id": "e_evt_workers",
      "kind": "edge",
      "from": {
        "elementId": "event_bus"
      },
      "to": {
        "elementId": "workers"
      },
      "label": "consumes",
      "router": "orthogonal",
      "style": {
        "dash": [
          4,
          4
        ]
      }
    },
    {
      "id": "e_sched_workers",
      "kind": "edge",
      "from": {
        "elementId": "scheduler"
      },
      "to": {
        "elementId": "workers"
      },
      "router": "orthogonal"
    },
    {
      "id": "e_workers_notifs",
      "kind": "edge",
      "from": {
        "elementId": "workers"
      },
      "to": {
        "elementId": "notifs"
      },
      "label": "triggers",
      "router": "orthogonal",
      "style": {
        "dash": [
          4,
          4
        ]
      }
    },
    {
      "id": "e_workers_storage",
      "kind": "edge",
      "from": {
        "elementId": "workers"
      },
      "to": {
        "elementId": "storage"
      },
      "label": "writes",
      "router": "orthogonal"
    },
    {
      "id": "e_payments_stripe",
      "kind": "edge",
      "from": {
        "elementId": "payments"
      },
      "to": {
        "elementId": "stripe"
      },
      "label": "charges",
      "router": "orthogonal"
    },
    {
      "id": "e_notifs_sendgrid",
      "kind": "edge",
      "from": {
        "elementId": "notifs"
      },
      "to": {
        "elementId": "sendgrid"
      },
      "label": "emails",
      "router": "orthogonal"
    },
    {
      "id": "e_services_obs",
      "kind": "edge",
      "from": {
        "elementId": "services"
      },
      "to": {
        "elementId": "observability"
      },
      "label": "telemetry",
      "router": "orthogonal"
    }
  ]
}

Agent workflow

Build a service-architecture diagram of an entire codebase by scanning the repository, deriving services / databases / queues / external dependencies from configuration files, and patching the saved Zindex diagram incrementally on each later scan.

Inputs

  • Repository checkout (full clone, default branch)
  • Convention map: which directory layouts mean 'this is a service' (e.g. services/*/Dockerfile, apps/*/package.json, internal/cmd/*)
  • Detector list: regexes / dep-graph patterns that identify databases (postgres URL strings), queues (Kafka topics, SQS queue names), external systems (Stripe SDK imports, Sendgrid API keys)
  • The diagram's Zindex ID or key (long-lived; one per repository)
  • A Zindex API key, or an MCP client signed in to Zindex

Outputs

  • A new revision of the diagram with frames for each tier (clients / edge / API / services / data / async / observability / external) and one node per detected component
  • Rendered SVG suitable for embedding in the repository's README or docs site
  • Revision history that doubles as an architecture changelog (each revision message describes what shipped that day / week)
  • Optional: a summary of newly-detected components since an earlier revision or date
  1. 01

    Read the diagram

    Architecture diagrams are long-lived (revisions stretch across months). Read the current outline before deriving anything new: its first line gives the revision you will edit against, and each line after it gives an element's ID, type and label, with each tier frame's children indented under it.

    diagram_get GET /v1/diagrams/${SCENE_ID}
  2. 02

    Scan the repository for components

    Walk the directory tree applying the convention map: directories matching services/*/Dockerfile become service nodes, apps/*/package.json become app nodes. Apply the detector list against every source file: database URL strings → database nodes; queue topic / queue-name imports → queue nodes; SDK package names → external-system nodes. Group everything into the canonical eight-tier frame layout (clients, edge, API, services, data, async, observability, external).

  3. 03

    Derive edges from imports and config

    For each component, derive its outbound dependencies. Service A imports service-B's SDK → edge A→B. Service A reads from queue Q → edge A→Q (publishes); service B reads queue Q → edge Q→B (consumes), styled dashed for async. Service A's config contains a database URL → edge A→database. Service A imports Stripe SDK → edge A→stripe (external). Reuse stable element ids derived from directory paths so renames don't churn the graph.

  4. 04

    Compute the operation diff

    Compare the parsed (component, edge) tuple against the diagram. New components → createNode. Removed components → deleteElement. New edges → createEdge. Changed labels → updateEdge. No op adds a child to an existing frame, so to place a new component in its tier frame, delete the frame and create it again in the same edit with the new children list and its layout, and create again any edge drawn from that frame, since deleting the frame deletes those edges. A tier frame keeps the size its layout gives it, so make it big enough for the new component; the engine places a component without a layout inside its frame where there is room, and NODE_OUTSIDE_FRAME warns when there isn't. Use autoLayout only with elements: without them it drops the tier frames' layout and lays every node out again by its edges, so the tiers lose their arrangement.

  5. 05

    Save the changes as one edit

    One diagram_edit with baseRevision set to the revision you read and a message that says what changed: 'add notifications service; consume orders.placed event' is more useful in the history than 'sync from main'. The edit is all or nothing: if an operation has errors, it returns VALIDATION_FAILED and saves nothing. If the diagram changed after you read it, the call returns REVISION_CONFLICT with what changed; re-plan against the new revision.

    diagram_edit POST /v1/diagrams/${SCENE_ID}/revisions
  6. 06

    Fix what the warnings report

    The edit's warnings list what checking and drawing the new revision noticed, each with a code, the element when there is one, and a one-line fix. LABEL_DUPLICATION_DETECTED means edges that start or end at one element share a label. An edge drawn from a whole tier frame, such as services to observability, returns EDGE_ENDPOINT_KIND_INVALID; keep it when the edge means the whole layer. Fix anything else with a follow-up edit.

  7. 07

    Render the new revision

    Get SVG and PNG links to the new revision; they work without a key for 7 days. Tier frames are translucent and dashed, so the components inside them read clearly. Download the SVG and commit it next to the repository README (or the docs site's /architecture.svg), since the links expire. Each revision's image is drawn once and kept, and prints its address, zindex.ai/d/<id>@<revision>, and date.

    diagram_render GET /v1/diagrams/${SCENE_ID}/render
  8. 08

    Optional: summarize recent changes

    Call diagram_history with compare: { from }, where from is an earlier revision or a date such as a week ago; to defaults to the latest revision. Summarize the element IDs it lists as added, changed and removed for the team: new services, retired services, and new external dependencies.

    diagram_history GET /v1/diagrams/${SCENE_ID}/compare?from=${WEEK_AGO}

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_get Read the diagram
  2. 02 diagram_edit Save the changes as one edit
  3. 03 diagram_render Render the new revision
  4. 04 diagram_history Optional: summarize recent changes

Unique tools used: 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 architecture diagram of a codebase that the team keeps in Zindex. When asked to update it, you scan the repository and change the diagram with typed edits for whatever has been added, removed, or rewired since its last revision, each with a message saying what changed. Every revision is kept, so the team can open the architecture as it was on any date.

The diagram's Zindex ID is `${SCENE_ID}`; it already exists. The diagram is long-lived - you will never recreate it. Each update computes the smallest valid set of typed operations that move the diagram from its current revision to one that matches what the scan found. Over months, the revision history reads as an architecture changelog.

Steps for each update:

1. Call `diagram_get({ id: "${SCENE_ID}" })`. The outline's first line gives the current revision (`r145`, for example), and each line after it gives one element's ID, type and label, with every tier frame's children indented under it. You need both the revision and the elements for the next steps.

2. Walk the repository, applying the convention map you've been given. The canonical map for typical monorepos: `services/*/Dockerfile` directories are service nodes; `apps/*/package.json` directories are application nodes. The directory name (or `name` field in `package.json` / `go.mod`) becomes the stable element id - never re-derive ids on every update; the long-lived stable id is what makes the revision history meaningful across renames.

3. Apply the detector list against every source file. Database URL strings (`postgres://`, `redis://`) → a database node. Queue topic / queue-name imports → a queue node. Imports of external SDK packages (`stripe`, `@sendgrid/mail`, `@aws-sdk/client-s3`) → an externalSystem node. Each detected component lands in the appropriate tier frame (clients, edge, API, services, data, async, observability, external).

4. Derive edges from imports and config. Service A imports `@acme/sdk-b` → edge A→B. Service A's config references a database URL → edge A→database. Service A reads from queue Q → edge Q→A (consumes), styled dashed; service B publishes to Q → edge B→Q (publishes), also dashed. Reuse stable edge ids built from `e_${from_id}_${to_id}` so re-running doesn't churn edge identities.

5. Diff what you parsed against what's in the diagram. New components → `createNode`. Removed components → `deleteElement`. New edges → `createEdge`. Changed edge labels → `updateEdge`. Renamed components → `updateNode` (do not delete-and-create, or you'll lose the edges and frame membership). No op adds a child to an existing frame, so to put a new component in its tier frame, delete the frame and create it again in the same edit with the new `children` list and its `layout`; deleting a frame also deletes the edges drawn from it, so create those again too. A tier frame keeps the size its `layout` gives it, so make that `layout` big enough for the new component, and give the component a `layout` inside it, or leave that out and the engine places the component inside where there is room. A `NODE_OUTSIDE_FRAME` warning means it didn't fit: move it with `updateNode`, or enlarge the frame with `resizeElement`.

6. 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. The `message` should describe what changed - 'add notifications service; consume orders.placed event' is far more useful long-term than 'sync from main'. If nothing changed, send nothing; an edit that changes nothing returns `noop: true` and makes no revision. If it returns `REVISION_CONFLICT`, someone changed the diagram after you read it: the error lists what changed, so re-plan against the new revision.

7. An edit with errors returns `VALIDATION_FAILED` and saves nothing. A saved edit returns `warnings`: what checking and drawing the new revision noticed, each with a `code`, the `element` when there is one, and a one-line `fix`. `LABEL_DUPLICATION_DETECTED` means edges that start or end at one element share a label, such as two services with a generic 'queries' label to the same database; give each its own. An edge drawn from a whole tier frame, such as `services` to `observability`, returns `EDGE_ENDPOINT_KIND_INVALID`; keep it when the edge means the whole layer, and fix anything else with a follow-up edit.

8. Call `diagram_render({ id: "${SCENE_ID}" })`. It returns SVG and PNG links to the new revision, valid for 7 days, not the image itself. Download the SVG and commit it next to the README (for example `docs/architecture.svg`), so the diagram becomes ambient documentation without a link that expires. Each revision's image is drawn once and kept, and prints its address, `zindex.ai/d/<id>@<revision>`, and date.

9. Once a week, call `diagram_history({ id: "${SCENE_ID}", compare: { from: "<the date a week ago, such as 2026-09-29>" } })` and post a short Slack message to the platform / engineering channel summarizing new services, retired services, and new external dependencies. `from` takes a revision number or a date, and `to` defaults to the latest revision. The diagram becomes an ambient awareness signal rather than a thing engineers only consult during onboarding.

Hard rules: never hand-edit the rendered SVG. Never recreate the diagram - always patch with stable ids. Never collapse a multi-tier topology into a single rank - the eight-tier frame layout is what makes the diagram readable as the system grows; preserve frame containment with each new node. Use `autoLayout` only with `elements`, naming the nodes to place again: without `elements` it drops the tier frames' `layout` and lays every node out again by its edges, so the tiers lose their arrangement.

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

    Architecture diagrams are long-lived (revisions stretch across months). Read the current outline before deriving anything new: its first line gives the revision you will edit against, and each line after it gives an element's ID, type and label, with each tier frame's children indented under it.

  2. 02 POST /v1/diagrams/${SCENE_ID}/revisions

    One diagram_edit with baseRevision set to the revision you read and a message that says what changed: 'add notifications service; consume orders.placed event' is more useful in the history than 'sync from main'. The edit is all or nothing: if an operation has errors, it returns VALIDATION_FAILED and saves nothing. If the diagram changed after you read it, the call returns REVISION_CONFLICT with what changed; re-plan against the new revision.

  3. 03 GET /v1/diagrams/${SCENE_ID}/render

    Get SVG and PNG links to the new revision; they work without a key for 7 days. Tier frames are translucent and dashed, so the components inside them read clearly. Download the SVG and commit it next to the repository README (or the docs site's /architecture.svg), since the links expire. Each revision's image is drawn once and kept, and prints its address, zindex.ai/d/<id>@<revision>, and date.

  4. 04 GET /v1/diagrams/${SCENE_ID}/compare?from=${WEEK_AGO}

    Call diagram_history with compare: { from }, where from is an earlier revision or a date such as a week ago; to defaults to the latest revision. Summarize the element IDs it lists as added, changed and removed for the team: new services, retired services, and new external dependencies.

Operations

Raw

The typed operations that build this diagram from empty. 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.

  • 54 operations
  • 22 createEdge, 8 createFrame, 24 createNode
{
  "schemaVersion": "0.1",
  "sceneId": "saas-platform",
  "baseRevision": 1,
  "message": "Initial repo-derived architecture: clients, edge, API, services, data, async, observability, external",
  "ops": [
    {
      "op": "createFrame",
      "id": "clients",
      "title": "Clients",
      "containerType": "generic",
      "children": [
        "web",
        "mobile",
        "api_consumer"
      ],
      "style": {
        "fill": "rgba(255, 255, 255, 0.5)",
        "dash": [
          4,
          4
        ],
        "cornerRadius": 8
      },
      "layout": {
        "mode": "absolute",
        "x": 40,
        "y": 30,
        "width": 1080,
        "height": 170
      }
    },
    {
      "op": "createFrame",
      "id": "edge",
      "title": "Edge",
      "containerType": "generic",
      "children": [
        "cdn",
        "waf"
      ],
      "style": {
        "fill": "rgba(255, 255, 255, 0.5)",
        "dash": [
          4,
          4
        ],
        "cornerRadius": 8
      },
      "layout": {
        "mode": "absolute",
        "x": 40,
        "y": 220,
        "width": 1080,
        "height": 170
      }
    },
    {
      "op": "createFrame",
      "id": "api",
      "title": "API Layer",
      "containerType": "generic",
      "children": [
        "gateway",
        "auth"
      ],
      "style": {
        "fill": "rgba(255, 255, 255, 0.5)",
        "dash": [
          4,
          4
        ],
        "cornerRadius": 8
      },
      "layout": {
        "mode": "absolute",
        "x": 40,
        "y": 410,
        "width": 1080,
        "height": 170
      }
    },
    {
      "op": "createFrame",
      "id": "services",
      "title": "Services",
      "containerType": "generic",
      "children": [
        "users",
        "catalog",
        "orders",
        "payments",
        "notifs"
      ],
      "style": {
        "fill": "rgba(255, 255, 255, 0.5)",
        "dash": [
          4,
          4
        ],
        "cornerRadius": 8
      },
      "layout": {
        "mode": "absolute",
        "x": 40,
        "y": 600,
        "width": 1080,
        "height": 170
      }
    },
    {
      "op": "createFrame",
      "id": "async",
      "title": "Async",
      "containerType": "generic",
      "children": [
        "event_bus",
        "workers",
        "scheduler"
      ],
      "style": {
        "fill": "rgba(255, 255, 255, 0.5)",
        "dash": [
          4,
          4
        ],
        "cornerRadius": 8
      },
      "layout": {
        "mode": "absolute",
        "x": 40,
        "y": 790,
        "width": 1080,
        "height": 170
      }
    },
    {
      "op": "createFrame",
      "id": "data",
      "title": "Data Plane",
      "containerType": "generic",
      "children": [
        "postgres",
        "redis",
        "search",
        "storage"
      ],
      "style": {
        "fill": "rgba(255, 255, 255, 0.5)",
        "dash": [
          4,
          4
        ],
        "cornerRadius": 8
      },
      "layout": {
        "mode": "absolute",
        "x": 40,
        "y": 980,
        "width": 1080,
        "height": 170
      }
    },
    {
      "op": "createFrame",
      "id": "observability",
      "title": "Observability",
      "containerType": "generic",
      "children": [
        "logs",
        "metrics",
        "tracing"
      ],
      "style": {
        "fill": "rgba(255, 255, 255, 0.5)",
        "dash": [
          4,
          4
        ],
        "cornerRadius": 8
      },
      "layout": {
        "mode": "absolute",
        "x": 1160,
        "y": 30,
        "width": 220,
        "height": 550
      }
    },
    {
      "op": "createFrame",
      "id": "external",
      "title": "External",
      "containerType": "generic",
      "children": [
        "stripe",
        "sendgrid"
      ],
      "style": {
        "fill": "rgba(255, 255, 255, 0.5)",
        "dash": [
          4,
          4
        ],
        "cornerRadius": 8
      },
      "layout": {
        "mode": "absolute",
        "x": 1160,
        "y": 600,
        "width": 220,
        "height": 540
      }
    },
    {
      "op": "createNode",
      "id": "web",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Web App",
      "icon": "lucide:monitor",
      "layout": {
        "mode": "absolute",
        "x": 230,
        "y": 75,
        "width": 180,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "mobile",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Mobile App",
      "icon": "lucide:smartphone",
      "layout": {
        "mode": "absolute",
        "x": 490,
        "y": 75,
        "width": 180,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "api_consumer",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Public API",
      "icon": "lucide:code",
      "layout": {
        "mode": "absolute",
        "x": 750,
        "y": 75,
        "width": 180,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "cdn",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "CDN",
      "icon": "lucide:globe",
      "layout": {
        "mode": "absolute",
        "x": 330,
        "y": 265,
        "width": 200,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "waf",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "WAF",
      "icon": "lucide:shield",
      "layout": {
        "mode": "absolute",
        "x": 630,
        "y": 265,
        "width": 200,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "gateway",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "API Gateway",
      "icon": "lucide:network",
      "layout": {
        "mode": "absolute",
        "x": 330,
        "y": 455,
        "width": 200,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "auth",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Auth Service",
      "icon": "lucide:lock",
      "layout": {
        "mode": "absolute",
        "x": 630,
        "y": 455,
        "width": 200,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "users",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Users",
      "icon": "lucide:users",
      "layout": {
        "mode": "absolute",
        "x": 110,
        "y": 645,
        "width": 140,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "catalog",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Catalog",
      "icon": "lucide:boxes",
      "layout": {
        "mode": "absolute",
        "x": 310,
        "y": 645,
        "width": 140,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "orders",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Orders",
      "icon": "lucide:package",
      "layout": {
        "mode": "absolute",
        "x": 510,
        "y": 645,
        "width": 140,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "payments",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Payments",
      "icon": "lucide:layers",
      "layout": {
        "mode": "absolute",
        "x": 710,
        "y": 645,
        "width": 140,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "notifs",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Notifications",
      "icon": "lucide:bell",
      "layout": {
        "mode": "absolute",
        "x": 910,
        "y": 645,
        "width": 140,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "event_bus",
      "nodeType": "queue",
      "shape": "roundedRect",
      "label": "Event Bus",
      "icon": "lucide:zap",
      "layout": {
        "mode": "absolute",
        "x": 230,
        "y": 835,
        "width": 180,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "workers",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Workers",
      "icon": "lucide:cpu",
      "layout": {
        "mode": "absolute",
        "x": 490,
        "y": 835,
        "width": 180,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "scheduler",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Scheduler",
      "icon": "lucide:clock",
      "layout": {
        "mode": "absolute",
        "x": 750,
        "y": 835,
        "width": 180,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "postgres",
      "nodeType": "database",
      "shape": "cylinder",
      "label": "PostgreSQL",
      "icon": "lucide:database",
      "layout": {
        "mode": "absolute",
        "x": 170,
        "y": 1010,
        "width": 160,
        "height": 130
      }
    },
    {
      "op": "createNode",
      "id": "redis",
      "nodeType": "database",
      "shape": "cylinder",
      "label": "Redis",
      "icon": "lucide:database",
      "layout": {
        "mode": "absolute",
        "x": 390,
        "y": 1010,
        "width": 160,
        "height": 130
      }
    },
    {
      "op": "createNode",
      "id": "search",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Search Index",
      "icon": "lucide:search",
      "layout": {
        "mode": "absolute",
        "x": 610,
        "y": 1025,
        "width": 160,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "storage",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Object Storage",
      "icon": "lucide:hard-drive",
      "layout": {
        "mode": "absolute",
        "x": 830,
        "y": 1025,
        "width": 160,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "logs",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Logs",
      "icon": "lucide:terminal",
      "layout": {
        "mode": "absolute",
        "x": 1190,
        "y": 90,
        "width": 160,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "metrics",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Metrics",
      "icon": "lucide:bar-chart",
      "layout": {
        "mode": "absolute",
        "x": 1190,
        "y": 240,
        "width": 160,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "tracing",
      "nodeType": "service",
      "shape": "roundedRect",
      "label": "Tracing",
      "icon": "lucide:activity",
      "layout": {
        "mode": "absolute",
        "x": 1190,
        "y": 390,
        "width": 160,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "stripe",
      "nodeType": "externalSystem",
      "shape": "roundedRect",
      "label": "Payment\nProvider",
      "icon": "lucide:external-link",
      "layout": {
        "mode": "absolute",
        "x": 1190,
        "y": 700,
        "width": 160,
        "height": 110
      }
    },
    {
      "op": "createNode",
      "id": "sendgrid",
      "nodeType": "externalSystem",
      "shape": "roundedRect",
      "label": "Email\nProvider",
      "icon": "lucide:mail",
      "layout": {
        "mode": "absolute",
        "x": 1190,
        "y": 880,
        "width": 160,
        "height": 110
      }
    },
    {
      "op": "createEdge",
      "id": "e_web_cdn",
      "from": {
        "elementId": "web"
      },
      "to": {
        "elementId": "cdn"
      },
      "label": "HTTPS",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_mob_cdn",
      "from": {
        "elementId": "mobile"
      },
      "to": {
        "elementId": "cdn"
      },
      "label": "HTTPS",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_api_cdn",
      "from": {
        "elementId": "api_consumer"
      },
      "to": {
        "elementId": "cdn"
      },
      "label": "HTTPS",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_cdn_waf",
      "from": {
        "elementId": "cdn"
      },
      "to": {
        "elementId": "waf"
      },
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_waf_gw",
      "from": {
        "elementId": "waf"
      },
      "to": {
        "elementId": "gateway"
      },
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_gw_auth",
      "from": {
        "elementId": "gateway"
      },
      "to": {
        "elementId": "auth"
      },
      "label": "validates",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_gw_users",
      "from": {
        "elementId": "gateway"
      },
      "to": {
        "elementId": "users"
      },
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_gw_catalog",
      "from": {
        "elementId": "gateway"
      },
      "to": {
        "elementId": "catalog"
      },
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_gw_orders",
      "from": {
        "elementId": "gateway"
      },
      "to": {
        "elementId": "orders"
      },
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_orders_payments",
      "from": {
        "elementId": "orders"
      },
      "to": {
        "elementId": "payments"
      },
      "label": "triggers",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_users_db",
      "from": {
        "elementId": "users"
      },
      "to": {
        "elementId": "postgres"
      },
      "label": "queries",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_catalog_search",
      "from": {
        "elementId": "catalog"
      },
      "to": {
        "elementId": "search"
      },
      "label": "indexes",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_orders_db",
      "from": {
        "elementId": "orders"
      },
      "to": {
        "elementId": "postgres"
      },
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_orders_redis",
      "from": {
        "elementId": "orders"
      },
      "to": {
        "elementId": "redis"
      },
      "label": "cache",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_orders_evt",
      "from": {
        "elementId": "orders"
      },
      "to": {
        "elementId": "event_bus"
      },
      "label": "publishes",
      "router": "orthogonal",
      "style": {
        "dash": [
          4,
          4
        ]
      }
    },
    {
      "op": "createEdge",
      "id": "e_evt_workers",
      "from": {
        "elementId": "event_bus"
      },
      "to": {
        "elementId": "workers"
      },
      "label": "consumes",
      "router": "orthogonal",
      "style": {
        "dash": [
          4,
          4
        ]
      }
    },
    {
      "op": "createEdge",
      "id": "e_sched_workers",
      "from": {
        "elementId": "scheduler"
      },
      "to": {
        "elementId": "workers"
      },
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_workers_notifs",
      "from": {
        "elementId": "workers"
      },
      "to": {
        "elementId": "notifs"
      },
      "label": "triggers",
      "router": "orthogonal",
      "style": {
        "dash": [
          4,
          4
        ]
      }
    },
    {
      "op": "createEdge",
      "id": "e_workers_storage",
      "from": {
        "elementId": "workers"
      },
      "to": {
        "elementId": "storage"
      },
      "label": "writes",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_payments_stripe",
      "from": {
        "elementId": "payments"
      },
      "to": {
        "elementId": "stripe"
      },
      "label": "charges",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_notifs_sendgrid",
      "from": {
        "elementId": "notifs"
      },
      "to": {
        "elementId": "sendgrid"
      },
      "label": "emails",
      "router": "orthogonal"
    },
    {
      "op": "createEdge",
      "id": "e_services_obs",
      "from": {
        "elementId": "services"
      },
      "to": {
        "elementId": "observability"
      },
      "label": "telemetry",
      "router": "orthogonal"
    }
  ]
}

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 first scan. Revision 1 is the empty diagram and revision 2 applies the operations in ops.json, so the eight tier frames, every component and every dependency are added. Each later scan compares the same way and names only what that scan changed, so the history reads as the team's architecture changelog.

  • Revision 1 → 2
  • +54 added
  • -0 removed
  • ~0 changed

+ Added

  • clients
  • edge
  • api
  • services
  • async
  • data
  • observability
  • external
  • web
  • mobile
  • api_consumer
  • cdn
  • waf
  • gateway
  • auth
  • users
  • catalog
  • orders
  • payments
  • notifs
  • event_bus
  • workers
  • scheduler
  • postgres
  • redis
  • search
  • storage
  • logs
  • metrics
  • tracing
  • stripe
  • sendgrid
  • e_web_cdn
  • e_mob_cdn
  • e_api_cdn
  • e_cdn_waf
  • e_waf_gw
  • e_gw_auth
  • e_gw_users
  • e_gw_catalog
  • e_gw_orders
  • e_orders_payments
  • e_users_db
  • e_catalog_search
  • e_orders_db
  • e_orders_redis
  • e_orders_evt
  • e_evt_workers
  • e_sched_workers
  • e_workers_notifs
  • e_workers_storage
  • e_payments_stripe
  • e_notifs_sendgrid
  • e_services_obs

Raw compare response

{
  "id": "dgm_uJtvsC9Kj8g7",
  "from": 1,
  "to": 2,
  "added": [
    "clients",
    "edge",
    "api",
    "services",
    "async",
    "data",
    "observability",
    "external",
    "web",
    "mobile",
    "api_consumer",
    "cdn",
    "waf",
    "gateway",
    "auth",
    "users",
    "catalog",
    "orders",
    "payments",
    "notifs",
    "event_bus",
    "workers",
    "scheduler",
    "postgres",
    "redis",
    "search",
    "storage",
    "logs",
    "metrics",
    "tracing",
    "stripe",
    "sendgrid",
    "e_web_cdn",
    "e_mob_cdn",
    "e_api_cdn",
    "e_cdn_waf",
    "e_waf_gw",
    "e_gw_auth",
    "e_gw_users",
    "e_gw_catalog",
    "e_gw_orders",
    "e_orders_payments",
    "e_users_db",
    "e_catalog_search",
    "e_orders_db",
    "e_orders_redis",
    "e_orders_evt",
    "e_evt_workers",
    "e_sched_workers",
    "e_workers_notifs",
    "e_workers_storage",
    "e_payments_stripe",
    "e_notifs_sendgrid",
    "e_services_obs"
  ],
  "changed": [],
  "removed": [],
  "scene": [],
  "scenario": "The first scan. Revision 1 is the empty diagram and revision 2 applies the operations in ops.json, so the eight tier frames, every component and every dependency are added. Each later scan compares the same way and names only what that scan changed, so the history reads as the team's architecture changelog."
}

To compare two versions of your own diagram, call diagram_history with compare: { from, to }, or GET /v1/diagrams/{id}/compare with from and to, giving revision numbers or dates. With an API key, GET /v1/images/{id}@{to}.svg?from={from} draws the later version with what changed colored.

Agent resources

Machine-readable versions of this example. Agents should fetch these rather than scrape the rendered HTML.

  • living-architecture-docs.scene.json Canonical DSP scene Open
  • living-architecture-docs.ops.json Typed-operation envelope that builds the scene Open
  • living-architecture-docs.workflow.json Structured agent workflow (goal, inputs, outputs, steps) Open
  • living-architecture-docs.diff.json Sample diagram_history compare response Open
  • living-architecture-docs.svg Rendered diagram Open
  • living-architecture-docs.md Agent-readable markdown summary Open
  • /examples/index.json Manifest of all examples (cross-linked) Open