What this example shows
The “after” architecture for a proposed change that introduces a new Payments service plus its connections to Stripe, the orders flow, and PostgreSQL. Scroll to the Revision diff panel below to see the captured before and after diagrams, one above the other, along with the compare response from diagram_history, listing the five added elements: Payments, Stripe and the three new edges. The edit places Payments and Stripe in the columns they join, so no node already placed moves.
When to use it
When a proposed code change meaningfully changes the system’s shape - adds a new service, replaces a database, removes a dependency, swaps a vendor - and you want reviewers to see that before it lands. The agent records the proposed change as a new revision of the architecture scene, so the diff shows exactly which services and dependencies the change adds, removes, or rewires.
What the agent does
Asked to review a proposed change, the agent fetches the persisted “main” scene representing current production architecture, reads the change to identify added / removed / modified services and dependencies, applies typed operations (createNode, createEdge, deleteElement) to a fresh revision, and calls diagram_history with compare to list what changed against main. Over REST, the image endpoint draws the proposal with additions in green, removals in red and changes in amber, ready to share with reviewers.
Every revision is kept, so the history records each proposed change, whether it landed or not. The persisted-scene model means architectural state carries over from one change to the next without ever being regenerated from scratch.
What the output includes
- A “before” + “after” pair of architecture scenes per proposed change.
- A visual diff highlighting added (green), removed (red), and changed (amber) elements, drawn by the REST image endpoint.
- A compare JSON for programmatic consumers.
- Synthesized background bands grouping nodes by
nodeTypeviaextensions.autoGroup: "byNodeType"at the top of the document - the engine emits “Services”, “Databases”, and “External Systems” regions so reviewers see at a glance which architectural layer a new service lands in. - A revision history accessible via
diagram_historyshowing the architectural delta of each recorded change over time.
Rendered diagram
Revision 2 as Zindex saved it, from the edit to revision 1 that Revision diff shows. That edit moved no placed node Revision diff doesn't list, but the Playground draws the scene below from scratch, so its nodes can land elsewhere. Open the scene there to swap themes (clean / dark / blueprint / sketch).
Scene JSON
Raw
The DSP scene of revision 2, without the node positions Zindex saved with it. Open it in the
Playground, or send it as scene to
POST /v1/diagrams/preview, to draw it from scratch.
{
"schemaVersion": "0.1",
"diagramFamily": "architecture",
"scene": {
"id": "pr-architecture-after",
"title": "Architecture (after the proposed Payments service)",
"brief": "The system's architecture: the web client, the API gateway, the services, and the stores and external systems they use.\nA proposed change is drawn as a new revision and compared with the current one, so keep element IDs stable. Edges run from caller to callee, labeled with the protocol or what the call does.",
"units": "px",
"canvas": {
"width": 1100,
"height": 520
}
},
"extensions": {
"autoGroup": "byNodeType"
},
"layoutStrategy": {
"direction": "LR",
"nodeSpacing": 50,
"rankSpacing": 120
},
"elements": [
{
"id": "client",
"kind": "node",
"nodeType": "actor",
"shape": "roundedRect",
"label": "Web Client",
"icon": "lucide:globe"
},
{
"id": "gateway",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "API Gateway",
"icon": "lucide:network"
},
{
"id": "auth",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "Auth Service",
"icon": "lucide:lock"
},
{
"id": "users",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "Users Service",
"icon": "lucide:users"
},
{
"id": "orders",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "Orders Service",
"icon": "lucide:package"
},
{
"id": "payments",
"kind": "node",
"nodeType": "service",
"shape": "roundedRect",
"label": "Payments Service",
"icon": "lucide:credit-card"
},
{
"id": "stripe",
"kind": "node",
"nodeType": "externalSystem",
"shape": "roundedRect",
"label": "Stripe",
"icon": "lucide:external-link"
},
{
"id": "postgres",
"kind": "node",
"nodeType": "database",
"shape": "cylinder",
"label": "PostgreSQL",
"icon": "lucide:database"
},
{
"id": "redis",
"kind": "node",
"nodeType": "database",
"shape": "cylinder",
"label": "Redis",
"icon": "lucide:database"
},
{
"id": "e_client_gw",
"kind": "edge",
"from": {
"elementId": "client"
},
"to": {
"elementId": "gateway"
},
"label": "HTTPS",
"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_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_payments_stripe",
"kind": "edge",
"from": {
"elementId": "payments"
},
"to": {
"elementId": "stripe"
},
"label": "charges",
"router": "orthogonal"
},
{
"id": "e_users_db",
"kind": "edge",
"from": {
"elementId": "users"
},
"to": {
"elementId": "postgres"
},
"router": "orthogonal"
},
{
"id": "e_orders_db",
"kind": "edge",
"from": {
"elementId": "orders"
},
"to": {
"elementId": "postgres"
},
"router": "orthogonal"
},
{
"id": "e_payments_db",
"kind": "edge",
"from": {
"elementId": "payments"
},
"to": {
"elementId": "postgres"
},
"router": "orthogonal"
},
{
"id": "e_orders_redis",
"kind": "edge",
"from": {
"elementId": "orders"
},
"to": {
"elementId": "redis"
},
"label": "cache",
"router": "orthogonal"
}
]
} Agent workflow
Show the architectural impact of a proposed code change by deriving the architecture as the change would leave it, recording that as a revision of the team's architecture diagram, and sharing the visual diff with reviewers - so they see what services and dependencies the change adds or removes without re-reading the change set.
Inputs
- The proposed change (list of changed files)
- Repository checkout with the change applied AND at its base
- The Zindex ID or key of the diagram storing the architecture on the default branch (long-lived, never recreated)
- A Zindex API key (the colored diff image needs one), or an MCP client signed in to Zindex
Outputs
- Two revisions to compare: 'before' (= the default branch's revision) and 'after' (= the default branch plus the proposed change)
- Rendered before-after diagrams as separate SVGs, or one image with the changes colored
- Compare JSON listing added / changed / removed elements
- A diff summary with the rendered diagrams, ready to share with reviewers
- 01
Read the architecture diagram on main
Read the diagram representing the architecture on the default branch. Note the current revision number (MAIN_REVISION) from the outline's first line - that's the 'before' baseline.
- 02
Scan the repository with the proposed change
Check out the repository with the change applied. Run the same component-detection logic that the living-architecture workflow uses, but against the changed tree. Emit the (component, edge) tuple that represents what the architecture *would be* with the change.
- 03
Compute the operation batch for the proposed state
Diff the scan against the diagram. Emit a batch of operations (createNode for new services, deleteElement for removed ones, createEdge / deleteElement for changed dependencies) that moves the diagram to the proposed state.
- 04
Save the proposal as a revision
Call
diagram_editwith the computed ops,baseRevision= MAIN_REVISION and a message that names the change -proposal 1234: add Payments service. This creates a new revision (PROPOSAL_REVISION). Every revision is kept, so the message is how you find the proposal later. - 05
Compare the default branch's revision with the proposal
Call
diagram_historywithcompare: { from: MAIN_REVISION, to: PROPOSAL_REVISION }. The output lists the element IDs the change adds, changes and removes - far more reviewable than re-reading source files. - 06
Render before-and-after diagrams
Call
diagram_renderwithrevision: MAIN_REVISION(before), then withrevision: PROPOSAL_REVISION(after). Each returns SVG and PNG links that work without a key for 7 days. Both images print their address, which includes the revision number, so the reviewer can verify exactly which state each diagram represents. - 07
Optional: one image with the changes colored
With an API key, the image endpoint draws the proposal with what changed since MAIN_REVISION colored: added in green, removed in red, changed in amber.
diagram_renderand its signed links draw plain versions only, so an agent connected through MCP sign-in shares the two images and the compare instead. - 08
Share the architectural diff with reviewers
Share both rendered SVGs (or the colored image) and the compare summary where the change is reviewed, such as the code review. When the change lands, the next living-architecture update records the shipped state as a new revision.
- 09
If the change is dropped
The proposal revision no longer represents the default branch. Revisions are never deleted, so call
diagram_editwithrestoreRevision: MAIN_REVISION,baseRevisionset to the latest revision and a message saying the proposal was dropped. That makes a new revision equal to the default branch's state; the proposal stays in the history as a record of what was proposed.
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 architecture diagram on main - 02
diagram_editSave the proposal as a revision - 03
diagram_historyCompare the default branch's revision with the proposal - 04
diagram_renderRender before-and-after diagrams - 05
diagram_editIf the change is dropped
Unique tools used: diagram_get, diagram_edit, diagram_history, diagram_render.
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 help the team review a proposed code change by showing what it does to the architecture. The team keeps its architecture diagram in Zindex. You derive what the architecture would look like with the change, record that as a revision of the diagram with a message naming the change, and share the visual diff, so reviewers can see at a glance which services and dependencies the change adds, removes, or rewires.
The diagram's Zindex ID is `${SCENE_ID}`; it represents the architecture on the default branch, and the living-architecture workflow updates it when changes land. Revisions are permanent: the proposal you record stays in the history under its message, and step 8 covers what to do when the change is dropped.
Steps for each proposed change (and again when it is revised):
1. Call `diagram_get({ id: "${SCENE_ID}" })`. Read the current revision number from the outline's first line - call this `MAIN_REVISION`. This is the 'before' state for the diff.
2. Check out the repository with the proposed change. Run the same component-detection logic the living-architecture workflow uses (services from `services/*/Dockerfile`, databases from URL strings, queues from imports, external systems from SDK packages) - but apply it to the changed tree, not main's. Emit a `(components, edges)` tuple that represents the architecture *as the change would leave it*.
3. Compute the operation batch that would move the diagram from its current state to the proposed state. New components → `createNode`; removed components → `deleteElement`; changed labels / endpoints → `updateEdge`. Reuse stable element ids (the directory name / service name) so renames produce `updateNode` rather than delete-and-create.
4. Call `diagram_edit({ id: "${SCENE_ID}", baseRevision: MAIN_REVISION, message, ops })` with that batch and a `message` that names the change, such as `proposal 1234: add Payments service`. This produces a new revision; call this `PROPOSAL_REVISION`. If the batch changes nothing, the response carries `noop: true` and the current revision, and no new revision is made.
5. Call `diagram_history({ id: "${SCENE_ID}", compare: { from: MAIN_REVISION, to: PROPOSAL_REVISION } })`. It returns which elements were added, changed, or removed. This is the answer to 'what does this change do to the architecture?' - and it is what you share with reviewers.
6. Render the 'before' and 'after' diagrams: `diagram_render({ id: "${SCENE_ID}", revision: MAIN_REVISION })`, then the same with `revision: PROPOSAL_REVISION`. Each returns SVG and PNG links valid for 7 days. The address printed on both includes the revision number, so reviewers can verify which state each image represents. With an API key, `GET /v1/images/${SCENE_ID}@PROPOSAL_REVISION.svg?from=MAIN_REVISION` draws one image of the proposal with the changes colored (added green, removed red, changed amber) instead; `diagram_render` has no such option.
7. Share one message with the reviewers, for example in the code review: the diff summary (`+1 service, -2 edges, 1 service renamed`), the before SVG, the after SVG, and a short prose description if the diff is non-trivial. When the change is revised, update that message rather than adding another, so reviewers always see the latest comparison.
8. If the change lands, leave the diagram as it is; the next living-architecture update records the shipped state. If the change is dropped, call `diagram_edit({ id: "${SCENE_ID}", baseRevision: <the latest revision>, message, restoreRevision: MAIN_REVISION })` with a message saying so; the new revision equals MAIN_REVISION, so the latest revision shows the shipped architecture again. The proposal stays in the history either way, as a record of what was proposed.
Hard rules: name every proposal in its revision message, so the history shows which revisions were proposals and which shipped. Never collapse the diff into a single 'after' diagram without the 'before' for comparison; the value here is the comparison, not just the rendered output. If the diff is empty (the change is cosmetic or not architectural), say 'No architectural changes detected' so the reviewer knows the check ran but had nothing to report.
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}Read the diagram representing the architecture on the default branch. Note the current revision number (MAIN_REVISION) from the outline's first line - that's the 'before' baseline.
- 02
POST/v1/diagrams/${SCENE_ID}/revisionsCall
diagram_editwith the computed ops,baseRevision= MAIN_REVISION and a message that names the change -proposal 1234: add Payments service. This creates a new revision (PROPOSAL_REVISION). Every revision is kept, so the message is how you find the proposal later. - 03
GET/v1/diagrams/${SCENE_ID}/compare?from=${MAIN_REVISION}&to=${PROPOSAL_REVISION}Call
diagram_historywithcompare: { from: MAIN_REVISION, to: PROPOSAL_REVISION }. The output lists the element IDs the change adds, changes and removes - far more reviewable than re-reading source files. - 04
GET/v1/diagrams/${SCENE_ID}/render?revision=${MAIN_REVISION}Call
diagram_renderwithrevision: MAIN_REVISION(before), then withrevision: PROPOSAL_REVISION(after). Each returns SVG and PNG links that work without a key for 7 days. Both images print their address, which includes the revision number, so the reviewer can verify exactly which state each diagram represents. - 05
GET/v1/images/${SCENE_ID}@${PROPOSAL_REVISION}.svg?from=${MAIN_REVISION}With an API key, the image endpoint draws the proposal with what changed since MAIN_REVISION colored: added in green, removed in red, changed in amber.
diagram_renderand its signed links draw plain versions only, so an agent connected through MCP sign-in shares the two images and the compare instead. - 06
POST/v1/diagrams/${SCENE_ID}/revisionsThe proposal revision no longer represents the default branch. Revisions are never deleted, so call
diagram_editwithrestoreRevision: MAIN_REVISION,baseRevisionset to the latest revision and a message saying the proposal was dropped. That makes a new revision equal to the default branch's state; the proposal stays in the history as a record of what was proposed.
Operations
Raw The typed operations that build revision 2's scene from empty in one edit, not through the edit the diagram above was saved by. Save an
empty diagram with diagram_create, then send the
envelope's baseRevision, message and
ops to diagram_edit, or
POST /v1/diagrams/{id}/revisions. Each op
carries a stable id so subsequent runs can update the
same elements instead of regenerating.
{
"schemaVersion": "0.1",
"sceneId": "pr-architecture-after",
"baseRevision": 1,
"message": "Build the architecture with the proposed Payments service, Stripe and their connections",
"ops": [
{
"op": "createNode",
"id": "client",
"nodeType": "actor",
"shape": "roundedRect",
"label": "Web Client",
"icon": "lucide:globe"
},
{
"op": "createNode",
"id": "gateway",
"nodeType": "service",
"shape": "roundedRect",
"label": "API Gateway",
"icon": "lucide:network"
},
{
"op": "createNode",
"id": "auth",
"nodeType": "service",
"shape": "roundedRect",
"label": "Auth Service",
"icon": "lucide:lock"
},
{
"op": "createNode",
"id": "users",
"nodeType": "service",
"shape": "roundedRect",
"label": "Users Service",
"icon": "lucide:users"
},
{
"op": "createNode",
"id": "orders",
"nodeType": "service",
"shape": "roundedRect",
"label": "Orders Service",
"icon": "lucide:package"
},
{
"op": "createNode",
"id": "payments",
"nodeType": "service",
"shape": "roundedRect",
"label": "Payments Service",
"icon": "lucide:credit-card"
},
{
"op": "createNode",
"id": "stripe",
"nodeType": "externalSystem",
"shape": "roundedRect",
"label": "Stripe",
"icon": "lucide:external-link"
},
{
"op": "createNode",
"id": "postgres",
"nodeType": "database",
"shape": "cylinder",
"label": "PostgreSQL",
"icon": "lucide:database"
},
{
"op": "createNode",
"id": "redis",
"nodeType": "database",
"shape": "cylinder",
"label": "Redis",
"icon": "lucide:database"
},
{
"op": "createEdge",
"id": "e_client_gw",
"from": {
"elementId": "client"
},
"to": {
"elementId": "gateway"
},
"label": "HTTPS",
"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_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_payments_stripe",
"from": {
"elementId": "payments"
},
"to": {
"elementId": "stripe"
},
"label": "charges",
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e_users_db",
"from": {
"elementId": "users"
},
"to": {
"elementId": "postgres"
},
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e_orders_db",
"from": {
"elementId": "orders"
},
"to": {
"elementId": "postgres"
},
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e_payments_db",
"from": {
"elementId": "payments"
},
"to": {
"elementId": "postgres"
},
"router": "orthogonal"
},
{
"op": "createEdge",
"id": "e_orders_redis",
"from": {
"elementId": "orders"
},
"to": {
"elementId": "redis"
},
"label": "cache",
"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
A proposed change adds a Payments service and its Stripe integration. Five elements are new: the Payments and Stripe nodes, and the edges from Orders to Payments, from Payments to Stripe and from Payments to PostgreSQL. The title changes from 'before' to 'after' the proposal, so scene lists title. Reviewers see this list and the before and after diagrams in one message, which is quicker than working out from the code which services now talk to which.
- Revision 1 → 2
- +5 added
- -0 removed
- ~0 changed
- scene fields changed: title
+ Added
paymentsstripee_orders_paymentse_payments_stripee_payments_db
Raw compare response
{
"id": "dgm_r3NXfozJh3tR",
"from": 1,
"to": 2,
"added": [
"payments",
"stripe",
"e_orders_payments",
"e_payments_stripe",
"e_payments_db"
],
"changed": [],
"removed": [],
"scene": [
"title"
],
"scenario": "A proposed change adds a Payments service and its Stripe integration. Five elements are new: the Payments and Stripe nodes, and the edges from Orders to Payments, from Payments to Stripe and from Payments to PostgreSQL. The title changes from 'before' to 'after' the proposal, so scene lists title. Reviewers see this list and the before and after diagrams in one message, which is quicker than working out from the code which services now talk to which."
} Agent resources
Machine-readable versions of this example. Agents should fetch these rather than scrape the rendered HTML.
-
pr-architecture-diff.scene.jsonCanonical DSP scene Open -
pr-architecture-diff.ops.jsonTyped-operation envelope that builds the scene Open -
pr-architecture-diff.workflow.jsonStructured agent workflow (goal, inputs, outputs, steps) Open -
pr-architecture-diff.diff.jsonSamplediagram_historycompare response Open -
pr-architecture-diff.svgRendered diagram: revision 2 as Zindex saved it Open -
pr-architecture-diff.before.svgRevision diff's before picture: revision 1 as Zindex saved it Open -
pr-architecture-diff.mdAgent-readable markdown summary Open -
/examples/index.jsonManifest of all examples (cross-linked) Open