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
layouton 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 warnsNODE_OUTSIDE_FRAME. The agent sendsautoLayoutonly withelements: without them, it drops the eight tier frames’layoutand lays every node out again by its edges: each tier stays round its members, but the arrangement of the tiers is lost.
Rendered diagram
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
- 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.
- 02
Scan the repository for components
Walk the directory tree applying the convention map: directories matching
services/*/Dockerfilebecome service nodes,apps/*/package.jsonbecome 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). - 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.
- 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
childrenlist and itslayout, and create again any edge drawn from that frame, since deleting the frame deletes those edges. A tier frame keeps the size itslayoutgives it, so make it big enough for the new component; the engine places a component without alayoutinside its frame where there is room, and NODE_OUTSIDE_FRAME warns when there isn't. UseautoLayoutonly withelements: without them it drops the tier frames'layoutand lays every node out again by its edges, so the tiers lose their arrangement. - 05
Save the changes as one edit
One
diagram_editwithbaseRevisionset to the revision you read and amessagethat 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 returnsVALIDATION_FAILEDand saves nothing. If the diagram changed after you read it, the call returnsREVISION_CONFLICTwith what changed; re-plan against the new revision. - 06
Fix what the warnings report
The edit's
warningslist what checking and drawing the new revision noticed, each with acode, theelementwhen there is one, and a one-linefix.LABEL_DUPLICATION_DETECTEDmeans edges that start or end at one element share a label. An edge drawn from a whole tier frame, such asservicestoobservability, returnsEDGE_ENDPOINT_KIND_INVALID; keep it when the edge means the whole layer. Fix anything else with a follow-up edit. - 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. - 08
Optional: summarize recent changes
Call
diagram_historywithcompare: { from }, wherefromis an earlier revision or a date such as a week ago;todefaults 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.
MCP recipe
For agents using Model Context Protocol. The tool sequence below matches the workflow steps; copy the prompt as a system message.
Tool sequence
- 01
diagram_getRead the diagram - 02
diagram_editSave the changes as one edit - 03
diagram_renderRender the new revision - 04
diagram_historyOptional: 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.
- 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.
- 02
POST/v1/diagrams/${SCENE_ID}/revisionsOne
diagram_editwithbaseRevisionset to the revision you read and amessagethat 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 returnsVALIDATION_FAILEDand saves nothing. If the diagram changed after you read it, the call returnsREVISION_CONFLICTwith what changed; re-plan against the new revision. - 03
GET/v1/diagrams/${SCENE_ID}/renderGet 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. - 04
GET/v1/diagrams/${SCENE_ID}/compare?from=${WEEK_AGO}Call
diagram_historywithcompare: { from }, wherefromis an earlier revision or a date such as a week ago;todefaults 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.
{
"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
clientsedgeapiservicesasyncdataobservabilityexternalwebmobileapi_consumercdnwafgatewayauthuserscatalogorderspaymentsnotifsevent_busworkersschedulerpostgresredissearchstoragelogsmetricstracingstripesendgride_web_cdne_mob_cdne_api_cdne_cdn_wafe_waf_gwe_gw_authe_gw_userse_gw_cataloge_gw_orderse_orders_paymentse_users_dbe_catalog_searche_orders_dbe_orders_redise_orders_evte_evt_workerse_sched_workerse_workers_notifse_workers_storagee_payments_stripee_notifs_sendgride_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.jsonCanonical DSP scene Open -
living-architecture-docs.ops.jsonTyped-operation envelope that builds the scene Open -
living-architecture-docs.workflow.jsonStructured agent workflow (goal, inputs, outputs, steps) Open -
living-architecture-docs.diff.jsonSamplediagram_historycompare response Open -
living-architecture-docs.svgRendered diagram Open -
living-architecture-docs.mdAgent-readable markdown summary Open -
/examples/index.jsonManifest of all examples (cross-linked) Open