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

AWS architecture diagram from Terraform

Let an agent draw a team's AWS architecture from its Terraform, as AWS reference diagrams draw it, and record each infrastructure pull request as a revision reviewers see before terraform apply.

architecture Terraform configuration / infrastructure pull requests scangenerateupdate

What this example shows

The production architecture of a bookings platform, drawn by an agent from the team’s Terraform as AWS reference diagrams draw it: AWS’s icons and group styles, the two Availability Zones side by side with their subnets in matching rows, the load balancer between them, the internet gateway on the VPC’s border, regional services beside the VPC and global services along the top. The agent wrote no coordinates. Revision 2 records pull request 412, which adds an SQS queue and a Lambda worker that resizes uploaded photos. Scroll to the Revision diff panel below to see both revisions, before and after, with the compare response from diagram_history. It lists the queue, the worker and their three edges as added, and as changed the Region they joined and the uploads bucket, which moved down the Region’s column to make room.

When to use it

When the infrastructure is defined in Terraform and the team wants an architecture diagram drawn from it, with each infrastructure pull request showing what it changes before terraform apply. A plan lists resources; the diagram shows where they run and what talks to what.

What the agent does

On the first run the agent reads the configuration on the default branch, makes a node with its AWS icon for each resource that runs or stores something, puts it in the AWS group it runs in, adds an edge for each connection the configuration grants, such as a load balancer’s targets or an IAM permission on a bucket, and saves the diagram with diagram_create. The engine places each group by what it is and routes the edges.

For each pull request that changes the infrastructure, the agent turns the new and removed resources into typed operations, a createNode that names the group to join, createEdge and deleteElement, and saves them with diagram_edit as a revision whose message names the pull request. The new services join the Region’s column next to the services they talk to, the uploads bucket moves down to make room, and nothing inside the VPC moves. diagram_history with compare lists what changed, and over REST the image endpoint draws the new revision with the additions in green, ready to post on the pull request.

What the output includes

  • One architecture diagram per environment, in AWS’s groups and icons on a dark canvas, that every later run edits rather than redraws.
  • A revision for each infrastructure pull request, its message starting with the pull request’s number.
  • A compare JSON listing the elements each pull request adds, changes and removes.
  • A colored image of each pull request’s revision, drawn by the REST image endpoint, with additions in green, removals in red and changes in amber.
  • For a pull request closed without merging, a revision that restores the one before it, so the latest revision shows what the default branch deploys.

Rendered diagram

AWS architecture diagram from Terraform - revision 2

Open full size

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": "aws-architecture-from-terraform",
    "title": "Bookings platform on AWS (production)",
    "brief": "Production AWS architecture of the bookings platform, drawn from the Terraform in infra/production.\nDrawn as AWS reference diagrams are: aws.* group frames nested AWS Cloud > Region > VPC > Availability Zone > subnets, and one node per resource that runs or stores something, with its aws: icon, in the innermost group it runs in. Each AZ lists its public subnet first, then its app and data subnets. The Bookings API runs one task per AZ; its calls to regional services are drawn from the task in AZ B. Logging is one edge from the VPC to CloudWatch. Edges run from caller to callee. Leave layout off new elements: the engine places them. Each infrastructure pull request is recorded as a revision before terraform apply, its message starting with the PR number (PR 412: ...).",
    "units": "px",
    "canvas": {
      "width": 1600,
      "height": 1200,
      "background": "#1a1a22"
    }
  },
  "palette": {
    "background": "#1a1a22",
    "foreground": "#FFFFFF",
    "edgeStroke": "#8FA7C4",
    "mutedForeground": "#c9d1d9"
  },
  "elements": [
    {
      "id": "aws_cloud",
      "kind": "frame",
      "title": "AWS Cloud",
      "containerType": "aws.cloud",
      "children": [
        "route53",
        "cloudfront",
        "waf",
        "region"
      ]
    },
    {
      "id": "region",
      "kind": "frame",
      "title": "Region us-east-1",
      "containerType": "aws.region",
      "children": [
        "vpc",
        "cognito",
        "s3_assets",
        "s3_uploads",
        "cloudwatch",
        "sqs",
        "worker"
      ]
    },
    {
      "id": "vpc",
      "kind": "frame",
      "title": "VPC 10.0.0.0/16",
      "containerType": "aws.vpc",
      "children": [
        "igw",
        "alb",
        "az_a",
        "az_b"
      ]
    },
    {
      "id": "az_a",
      "kind": "frame",
      "title": "Availability Zone A",
      "containerType": "aws.az",
      "children": [
        "pub_a",
        "app_a",
        "data_a"
      ]
    },
    {
      "id": "az_b",
      "kind": "frame",
      "title": "Availability Zone B",
      "containerType": "aws.az",
      "children": [
        "pub_b",
        "app_b",
        "data_b"
      ]
    },
    {
      "id": "pub_a",
      "kind": "frame",
      "title": "Public subnet",
      "containerType": "aws.subnet.public",
      "children": [
        "nat_a"
      ]
    },
    {
      "id": "pub_b",
      "kind": "frame",
      "title": "Public subnet",
      "containerType": "aws.subnet.public",
      "children": [
        "nat_b"
      ]
    },
    {
      "id": "app_a",
      "kind": "frame",
      "title": "Private subnet (app)",
      "containerType": "aws.subnet.private",
      "children": [
        "svc_a"
      ]
    },
    {
      "id": "app_b",
      "kind": "frame",
      "title": "Private subnet (app)",
      "containerType": "aws.subnet.private",
      "children": [
        "svc_b"
      ]
    },
    {
      "id": "data_a",
      "kind": "frame",
      "title": "Private subnet (data)",
      "containerType": "aws.subnet.private",
      "children": [
        "cache_a",
        "aurora_w"
      ]
    },
    {
      "id": "data_b",
      "kind": "frame",
      "title": "Private subnet (data)",
      "containerType": "aws.subnet.private",
      "children": [
        "aurora_r",
        "cache_b"
      ]
    },
    {
      "id": "users",
      "kind": "node",
      "nodeType": "actor",
      "label": "Customers",
      "icon": "aws:users"
    },
    {
      "id": "route53",
      "kind": "node",
      "nodeType": "service",
      "label": "Amazon Route 53",
      "icon": "aws:route53"
    },
    {
      "id": "cloudfront",
      "kind": "node",
      "nodeType": "service",
      "label": "Amazon CloudFront",
      "icon": "aws:cloudfront"
    },
    {
      "id": "waf",
      "kind": "node",
      "nodeType": "service",
      "label": "AWS WAF",
      "icon": "aws:waf"
    },
    {
      "id": "igw",
      "kind": "node",
      "nodeType": "service",
      "label": "Internet gateway",
      "icon": "aws:internet-gateway"
    },
    {
      "id": "alb",
      "kind": "node",
      "nodeType": "service",
      "label": "Application Load Balancer",
      "icon": "aws:application-load-balancer"
    },
    {
      "id": "nat_a",
      "kind": "node",
      "nodeType": "service",
      "label": "NAT gateway",
      "icon": "aws:nat-gateway"
    },
    {
      "id": "nat_b",
      "kind": "node",
      "nodeType": "service",
      "label": "NAT gateway",
      "icon": "aws:nat-gateway"
    },
    {
      "id": "svc_a",
      "kind": "node",
      "nodeType": "service",
      "label": "Bookings API task",
      "icon": "aws:ecs-task"
    },
    {
      "id": "svc_b",
      "kind": "node",
      "nodeType": "service",
      "label": "Bookings API task",
      "icon": "aws:ecs-task"
    },
    {
      "id": "cache_a",
      "kind": "node",
      "nodeType": "database",
      "label": "ElastiCache primary",
      "icon": "aws:elasticache"
    },
    {
      "id": "aurora_w",
      "kind": "node",
      "nodeType": "database",
      "label": "Aurora writer",
      "icon": "aws:aurora"
    },
    {
      "id": "aurora_r",
      "kind": "node",
      "nodeType": "database",
      "label": "Aurora reader",
      "icon": "aws:aurora"
    },
    {
      "id": "cache_b",
      "kind": "node",
      "nodeType": "database",
      "label": "ElastiCache replica",
      "icon": "aws:elasticache"
    },
    {
      "id": "cognito",
      "kind": "node",
      "nodeType": "service",
      "label": "Amazon Cognito",
      "icon": "aws:cognito"
    },
    {
      "id": "s3_assets",
      "kind": "node",
      "nodeType": "objectStorage",
      "label": "S3 web assets",
      "icon": "aws:s3"
    },
    {
      "id": "s3_uploads",
      "kind": "node",
      "nodeType": "objectStorage",
      "label": "S3 uploads",
      "icon": "aws:s3"
    },
    {
      "id": "cloudwatch",
      "kind": "node",
      "nodeType": "service",
      "label": "Amazon CloudWatch",
      "icon": "aws:cloudwatch"
    },
    {
      "id": "sqs",
      "kind": "node",
      "nodeType": "queue",
      "label": "Amazon SQS",
      "icon": "aws:sqs"
    },
    {
      "id": "worker",
      "kind": "node",
      "nodeType": "service",
      "label": "AWS Lambda worker",
      "icon": "aws:lambda"
    },
    {
      "id": "e_dns",
      "kind": "edge",
      "from": {
        "elementId": "users"
      },
      "to": {
        "elementId": "route53"
      },
      "label": "DNS"
    },
    {
      "id": "e_https",
      "kind": "edge",
      "from": {
        "elementId": "users"
      },
      "to": {
        "elementId": "cloudfront"
      },
      "label": "HTTPS"
    },
    {
      "id": "e_signin",
      "kind": "edge",
      "from": {
        "elementId": "users"
      },
      "to": {
        "elementId": "cognito"
      },
      "label": "sign in"
    },
    {
      "id": "e_waf",
      "kind": "edge",
      "from": {
        "elementId": "waf"
      },
      "to": {
        "elementId": "cloudfront"
      },
      "style": {
        "dash": [
          6,
          4
        ]
      },
      "endpoints": {
        "endArrow": "none"
      }
    },
    {
      "id": "e_static",
      "kind": "edge",
      "from": {
        "elementId": "cloudfront"
      },
      "to": {
        "elementId": "s3_assets"
      },
      "label": "static files"
    },
    {
      "id": "e_api",
      "kind": "edge",
      "from": {
        "elementId": "cloudfront"
      },
      "to": {
        "elementId": "igw"
      },
      "label": "/api/*"
    },
    {
      "id": "e_igw",
      "kind": "edge",
      "from": {
        "elementId": "igw"
      },
      "to": {
        "elementId": "alb"
      }
    },
    {
      "id": "e_alb_a",
      "kind": "edge",
      "from": {
        "elementId": "alb"
      },
      "to": {
        "elementId": "svc_a"
      }
    },
    {
      "id": "e_alb_b",
      "kind": "edge",
      "from": {
        "elementId": "alb"
      },
      "to": {
        "elementId": "svc_b"
      }
    },
    {
      "id": "e_cache_a",
      "kind": "edge",
      "from": {
        "elementId": "svc_a"
      },
      "to": {
        "elementId": "cache_a"
      }
    },
    {
      "id": "e_sql_a",
      "kind": "edge",
      "from": {
        "elementId": "svc_a"
      },
      "to": {
        "elementId": "aurora_w"
      }
    },
    {
      "id": "e_sql_b",
      "kind": "edge",
      "from": {
        "elementId": "svc_b"
      },
      "to": {
        "elementId": "aurora_w"
      },
      "label": "writes"
    },
    {
      "id": "e_read_b",
      "kind": "edge",
      "from": {
        "elementId": "svc_b"
      },
      "to": {
        "elementId": "aurora_r"
      },
      "label": "reads"
    },
    {
      "id": "e_cache_b",
      "kind": "edge",
      "from": {
        "elementId": "svc_b"
      },
      "to": {
        "elementId": "cache_b"
      }
    },
    {
      "id": "e_repl_db",
      "kind": "edge",
      "from": {
        "elementId": "aurora_w"
      },
      "to": {
        "elementId": "aurora_r"
      },
      "label": "replication",
      "style": {
        "dash": [
          6,
          4
        ]
      }
    },
    {
      "id": "e_repl_cache",
      "kind": "edge",
      "from": {
        "elementId": "cache_a"
      },
      "to": {
        "elementId": "cache_b"
      },
      "label": "replication",
      "style": {
        "dash": [
          6,
          4
        ]
      }
    },
    {
      "id": "e_logs",
      "kind": "edge",
      "from": {
        "elementId": "vpc"
      },
      "to": {
        "elementId": "cloudwatch"
      },
      "label": "logs, metrics"
    },
    {
      "id": "e_upload",
      "kind": "edge",
      "from": {
        "elementId": "svc_b"
      },
      "to": {
        "elementId": "s3_uploads"
      },
      "label": "originals"
    },
    {
      "id": "e_enqueue",
      "kind": "edge",
      "from": {
        "elementId": "svc_b"
      },
      "to": {
        "elementId": "sqs"
      },
      "label": "enqueue"
    },
    {
      "id": "e_trigger",
      "kind": "edge",
      "from": {
        "elementId": "sqs"
      },
      "to": {
        "elementId": "worker"
      },
      "label": "invokes"
    },
    {
      "id": "e_write",
      "kind": "edge",
      "from": {
        "elementId": "worker"
      },
      "to": {
        "elementId": "s3_uploads"
      },
      "label": "thumbnails"
    }
  ]
}

Agent workflow

Draw a team's AWS architecture diagram from its Terraform, once from the default branch and as AWS reference diagrams draw it, then record each infrastructure pull request as a revision named for it and share the compare and the colored diff on the pull request, so reviewers see what the change adds or removes before terraform apply.

Inputs

  • The Terraform configuration on the default branch (infra/production)
  • The pull request's diff of that configuration, or its plan as JSON (terraform show -json) when CI publishes one
  • The diagram's Zindex key, bookings-aws-production, or its ID from .zindex.json (long-lived, never recreated)
  • A Zindex API key (the colored diff image of a private diagram needs one), or an MCP client signed in to Zindex

Outputs

  • Revision 1: the production architecture drawn from the default branch, in AWS's groups and icons, laid out by the engine
  • One revision per infrastructure pull request, its message starting with the pull request's number
  • Compare JSON listing the elements the pull request adds, changes and removes
  • Before and after images, or one image with the changes colored, posted on the pull request
  1. 01

    Find the architecture diagram

    Call diagram_find with the diagram's key, bookings-aws-production, or read its ID from .zindex.json. If it exists, go to read_current. Over REST, GET /v1/diagrams/{key} answers 404 NOT_FOUND when there is none yet.

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

    Read the Terraform on the default branch

    Read infra/production on the default branch. Each resource that runs or stores something becomes a node with its aws: icon, in the innermost AWS group it runs in: the ECS service's tasks, the NAT gateways and the database and cache instances in their subnets, one per Availability Zone; the load balancer and the internet gateway in the VPC; S3, SQS, Cognito, CloudWatch and any Lambda function without vpc_config in the Region; Route 53, CloudFront and WAF in AWS Cloud; the customers outside it. Security groups, IAM, certificates, log groups, target groups and listeners aren't drawn. They become edges or nothing.

  3. 03

    Save the first drawing

    Call diagram_create with the key, a message naming the commit, and the scene: diagramFamily: "architecture", a frame per AWS group with its containerType (aws.cloud, aws.region, aws.vpc, aws.az, aws.subnet.public, aws.subnet.private), each Availability Zone listing its public subnet first, the nodes with their icons and short labels, an edge for each connection the configuration grants, and a brief that states these conventions. Leave layout and shape off. The engine arranges the groups as AWS reference diagrams do and draws each icon alone. AWS_GROUP_UNTYPED or AWS_GROUP_NESTING in the save's warnings names a group: do what its fix says.

    diagram_create POST /v1/diagrams
  4. 04

    Read the diagram's current revision

    For each pull request that changes infra/, call diagram_get. The outline's first line gives the current revision number (MAIN_REVISION), the 'before' state for the compare, and its lines list each element inside its group, so you can see which IDs already exist and which group a new resource joins.

    diagram_get GET /v1/diagrams/${SCENE_ID}
  5. 05

    Read the pull request's change

    Read the pull request's diff of infra/production, or the resource_changes of its plan when CI publishes terraform show -json. List the resources it creates and destroys, and the connections it adds or removes: an IAM permission on a queue or bucket, an event source mapping, a CloudFront origin, a target group's targets.

  6. 06

    Compute the operation batch

    New resources become createNode with frame set to the group they run in (an SQS queue and a Lambda function outside the VPC join region), a new subnet or Availability Zone createFrame with frame set to the group that holds it, new connections createEdge, destroyed resources deleteElement, renamed ones updateNode. Reuse the IDs the diagram already has and write no layout. A change that adds, removes or connects no drawn resource (instance sizes, tags, retention) isn't architectural.

  7. 07

    Save the pull request as a revision

    Call diagram_edit with the ops, baseRevision = MAIN_REVISION and a message that starts with the pull request's number: PR 412: resize uploaded photos in a Lambda worker fed by SQS. This creates PR_REVISION. The engine places the new services in the Region's column next to their neighbors, moves the uploads bucket down to make room and grows the Region; nothing inside the VPC moves. A batch that changes nothing answers noop: true, and no revision is made.

    diagram_edit POST /v1/diagrams/${SCENE_ID}/revisions
  8. 08

    Compare the default branch's revision with the pull request's

    Call diagram_history with compare: { from: MAIN_REVISION, to: PR_REVISION }. It lists the element IDs the pull request adds, changes and removes. For PR 412 that is the queue, the worker and their three edges added, and as changed the Region they joined and the uploads bucket the engine moved down to make room.

    diagram_history GET /v1/diagrams/${SCENE_ID}/compare?from=${MAIN_REVISION}&to=${PR_REVISION}
  9. 09

    Render both revisions

    Call diagram_render with revision: MAIN_REVISION, then with revision: PR_REVISION. Each returns SVG and PNG links that work without a key for 7 days, and each image prints its address with its revision number, so reviewers can tell which state they're looking at.

    diagram_render GET /v1/diagrams/${SCENE_ID}/render?revision=${MAIN_REVISION}
  10. 10

    Optional: one image with the changes colored

    With an API key, the image endpoint draws PR_REVISION with what changed since MAIN_REVISION colored, with additions in green, removals in red and changes in amber. A group whose only change is new members keeps its own color, so the new services stand out. diagram_render and its signed links draw plain versions only, so an agent signed in through MCP posts the two images and the compare instead.

    GET /v1/images/${SCENE_ID}@${PR_REVISION}.svg?from=${MAIN_REVISION}
  11. 11

    Post the change on the pull request

    Post one comment on the pull request before terraform apply runs: the summary (+2 services, +3 connections), the colored image or the two images, and the compare. When the pull request changes, record the difference as another revision with the same number, compare from MAIN_REVISION again, and update that comment rather than adding another.

  12. 12

    If the pull request is closed without merging

    The latest revision no longer matches what the default branch deploys. Call diagram_edit with restoreRevision: MAIN_REVISION, baseRevision set to the latest revision and a message saying the pull request was closed. The new revision equals MAIN_REVISION, and the pull request's revision stays in the history. A merged pull request needs nothing, since its revision already shows what terraform apply builds.

    diagram_edit POST /v1/diagrams/${SCENE_ID}/revisions

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_find Find the architecture diagram
  2. 02 diagram_create Save the first drawing
  3. 03 diagram_get Read the diagram's current revision
  4. 04 diagram_edit Save the pull request as a revision
  5. 05 diagram_history Compare the default branch's revision with the pull request's
  6. 06 diagram_render Render both revisions
  7. 07 diagram_edit If the pull request is closed without merging

Unique tools used: diagram_find, diagram_create, 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 look after the team's AWS architecture diagram, drawn from its Terraform, and show reviewers what each infrastructure pull request changes before `terraform apply`. You draw the diagram once from the default branch, as AWS reference diagrams draw it, then record each pull request that changes the infrastructure as a revision named for it.

The diagram's Zindex ID is `${SCENE_ID}` and its key is `bookings-aws-production`. The configuration is in `infra/production`. Revisions are permanent, so step 7 covers a pull request closed without merging.

How to draw it:
- `diagramFamily: "architecture"`, and a frame for each AWS group with its `containerType`, nested `aws.cloud` > `aws.region` > `aws.vpc` > `aws.az` > `aws.subnet.public` and `aws.subnet.private`. Each Availability Zone lists its public subnet first, then its private subnets in the same order as the other zones.
- A node for each resource that runs or stores something, with its `aws:` icon and a short label, in the innermost group it runs in: tasks, NAT gateways and database instances in their subnets, one per zone; the load balancer and internet gateway in the VPC; S3, SQS, Cognito, CloudWatch and Lambda functions without `vpc_config` in the Region; Route 53, CloudFront and WAF in AWS Cloud; customers outside it. Write no `layout`, `shape` or `fill`. The engine arranges the groups as AWS does and draws each icon alone. Security groups, IAM, certificates, log groups and target groups aren't drawn; they tell you the edges.
- An edge from caller to callee for each connection the configuration grants, labeled with what flows; dash replication. Draw calls to regional services from the task in the last zone, and logging as one edge from the VPC to CloudWatch.

Steps:

1. If you don't have the diagram's ID yet, call `diagram_find({ query: "bookings-aws-production" })`, which returns it. If there is none, build the scene from the default branch and call `diagram_create({ key: "bookings-aws-production", scene, message })` with a brief that states these conventions, and use the ID it returns. Act on any group the save's `warnings` name (`AWS_GROUP_UNTYPED`, `AWS_GROUP_NESTING`), as its fix says.

2. For each pull request that changes `infra/`, call `diagram_get({ id: "${SCENE_ID}" })`. Read the current revision number from the outline's first line; call this `MAIN_REVISION`. It is the 'before' state for the compare.

3. Read the pull request's diff, or its plan's `resource_changes` when CI publishes `terraform show -json`. New resources → `createNode` with `frame` set to the group they run in; a new subnet or Availability Zone → `createFrame` with `frame` set to the group that holds it and its first resource in `children`; new connections → `createEdge`; destroyed resources → `deleteElement`; renamed ones → `updateNode`. Reuse the diagram's IDs and write no `layout`. New nodes take a free place in their group, next to their neighbors. Where a subnet row or the Region's column is full, it opens there and what lies past it moves along; the save's `changed` names what moved.

4. Call `diagram_edit({ id: "${SCENE_ID}", baseRevision: MAIN_REVISION, message, ops })` with a message that starts with the pull request's number, such as `PR 412: resize uploaded photos in a Lambda worker fed by SQS`. Call the new revision `PR_REVISION`. If the batch changes nothing, the response carries `noop: true` and no revision is made.

5. Call `diagram_history({ id: "${SCENE_ID}", compare: { from: MAIN_REVISION, to: PR_REVISION } })` for the elements the pull request adds, changes and removes, then `diagram_render` with `revision: MAIN_REVISION` and with `revision: PR_REVISION` for SVG and PNG links valid for 7 days. With an API key, `GET /v1/images/${SCENE_ID}@PR_REVISION.svg?from=MAIN_REVISION` draws one image with additions in green, removals in red and changes in amber; `diagram_render` has no such option.

6. Post one comment on the pull request: the summary (`+2 services, +3 connections`), the images and the compare. When the pull request changes, record the difference as another revision with the same number and update that comment rather than adding another.

7. If the pull request merges, leave the diagram as it is. If it is closed without merging, call `diagram_edit({ id: "${SCENE_ID}", baseRevision: <the latest revision>, message, restoreRevision: MAIN_REVISION })` with a message saying so, so the latest revision shows what the default branch deploys again.

Hard rules: name the pull request in every revision message, so the history shows when each part of the architecture arrived. Never redraw the diagram or recreate an element to change it; the IDs carry its history. Never give a node a `layout`. If the pull request adds, removes or connects no drawn resource (instance sizes, tags, retention periods), post 'No architectural changes' so reviewers know the check ran, and record nothing.

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}

    Call diagram_find with the diagram's key, bookings-aws-production, or read its ID from .zindex.json. If it exists, go to read_current. Over REST, GET /v1/diagrams/{key} answers 404 NOT_FOUND when there is none yet.

  2. 02 POST /v1/diagrams

    Call diagram_create with the key, a message naming the commit, and the scene: diagramFamily: "architecture", a frame per AWS group with its containerType (aws.cloud, aws.region, aws.vpc, aws.az, aws.subnet.public, aws.subnet.private), each Availability Zone listing its public subnet first, the nodes with their icons and short labels, an edge for each connection the configuration grants, and a brief that states these conventions. Leave layout and shape off. The engine arranges the groups as AWS reference diagrams do and draws each icon alone. AWS_GROUP_UNTYPED or AWS_GROUP_NESTING in the save's warnings names a group: do what its fix says.

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

    For each pull request that changes infra/, call diagram_get. The outline's first line gives the current revision number (MAIN_REVISION), the 'before' state for the compare, and its lines list each element inside its group, so you can see which IDs already exist and which group a new resource joins.

  4. 04 POST /v1/diagrams/${SCENE_ID}/revisions

    Call diagram_edit with the ops, baseRevision = MAIN_REVISION and a message that starts with the pull request's number: PR 412: resize uploaded photos in a Lambda worker fed by SQS. This creates PR_REVISION. The engine places the new services in the Region's column next to their neighbors, moves the uploads bucket down to make room and grows the Region; nothing inside the VPC moves. A batch that changes nothing answers noop: true, and no revision is made.

    Example request body

    {
      "baseRevision": 1,
      "message": "PR 412: resize uploaded photos in a Lambda worker fed by SQS",
      "ops": [
        {
          "op": "createNode",
          "id": "sqs",
          "nodeType": "queue",
          "label": "Amazon SQS",
          "icon": "aws:sqs",
          "frame": "region"
        },
        {
          "op": "createNode",
          "id": "worker",
          "nodeType": "service",
          "label": "AWS Lambda worker",
          "icon": "aws:lambda",
          "frame": "region"
        },
        {
          "op": "createEdge",
          "id": "e_enqueue",
          "from": {
            "elementId": "svc_b"
          },
          "to": {
            "elementId": "sqs"
          },
          "label": "enqueue"
        },
        {
          "op": "createEdge",
          "id": "e_trigger",
          "from": {
            "elementId": "sqs"
          },
          "to": {
            "elementId": "worker"
          },
          "label": "invokes"
        },
        {
          "op": "createEdge",
          "id": "e_write",
          "from": {
            "elementId": "worker"
          },
          "to": {
            "elementId": "s3_uploads"
          },
          "label": "thumbnails"
        }
      ]
    }
  5. 05 GET /v1/diagrams/${SCENE_ID}/compare?from=${MAIN_REVISION}&to=${PR_REVISION}

    Call diagram_history with compare: { from: MAIN_REVISION, to: PR_REVISION }. It lists the element IDs the pull request adds, changes and removes. For PR 412 that is the queue, the worker and their three edges added, and as changed the Region they joined and the uploads bucket the engine moved down to make room.

  6. 06 GET /v1/diagrams/${SCENE_ID}/render?revision=${MAIN_REVISION}

    Call diagram_render with revision: MAIN_REVISION, then with revision: PR_REVISION. Each returns SVG and PNG links that work without a key for 7 days, and each image prints its address with its revision number, so reviewers can tell which state they're looking at.

  7. 07 GET /v1/images/${SCENE_ID}@${PR_REVISION}.svg?from=${MAIN_REVISION}

    With an API key, the image endpoint draws PR_REVISION with what changed since MAIN_REVISION colored, with additions in green, removals in red and changes in amber. A group whose only change is new members keeps its own color, so the new services stand out. diagram_render and its signed links draw plain versions only, so an agent signed in through MCP posts the two images and the compare instead.

  8. 08 POST /v1/diagrams/${SCENE_ID}/revisions

    The latest revision no longer matches what the default branch deploys. Call diagram_edit with restoreRevision: MAIN_REVISION, baseRevision set to the latest revision and a message saying the pull request was closed. The new revision equals MAIN_REVISION, and the pull request's revision stays in the history. A merged pull request needs nothing, since its revision already shows what terraform apply builds.

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.

  • 52 operations
  • 21 createEdge, 11 createFrame, 20 createNode
{
  "schemaVersion": "0.1",
  "sceneId": "aws-architecture-from-terraform",
  "baseRevision": 1,
  "message": "Build the production AWS architecture from infra/production, with PR 412's photo-resize queue and Lambda worker",
  "ops": [
    {
      "op": "createFrame",
      "id": "aws_cloud",
      "title": "AWS Cloud",
      "containerType": "aws.cloud",
      "children": [
        "route53",
        "cloudfront",
        "waf",
        "region"
      ]
    },
    {
      "op": "createFrame",
      "id": "region",
      "title": "Region us-east-1",
      "containerType": "aws.region",
      "children": [
        "vpc",
        "cognito",
        "s3_assets",
        "s3_uploads",
        "cloudwatch"
      ]
    },
    {
      "op": "createFrame",
      "id": "vpc",
      "title": "VPC 10.0.0.0/16",
      "containerType": "aws.vpc",
      "children": [
        "igw",
        "alb",
        "az_a",
        "az_b"
      ]
    },
    {
      "op": "createFrame",
      "id": "az_a",
      "title": "Availability Zone A",
      "containerType": "aws.az",
      "children": [
        "pub_a",
        "app_a",
        "data_a"
      ]
    },
    {
      "op": "createFrame",
      "id": "az_b",
      "title": "Availability Zone B",
      "containerType": "aws.az",
      "children": [
        "pub_b",
        "app_b",
        "data_b"
      ]
    },
    {
      "op": "createFrame",
      "id": "pub_a",
      "title": "Public subnet",
      "containerType": "aws.subnet.public",
      "children": [
        "nat_a"
      ]
    },
    {
      "op": "createFrame",
      "id": "pub_b",
      "title": "Public subnet",
      "containerType": "aws.subnet.public",
      "children": [
        "nat_b"
      ]
    },
    {
      "op": "createFrame",
      "id": "app_a",
      "title": "Private subnet (app)",
      "containerType": "aws.subnet.private",
      "children": [
        "svc_a"
      ]
    },
    {
      "op": "createFrame",
      "id": "app_b",
      "title": "Private subnet (app)",
      "containerType": "aws.subnet.private",
      "children": [
        "svc_b"
      ]
    },
    {
      "op": "createFrame",
      "id": "data_a",
      "title": "Private subnet (data)",
      "containerType": "aws.subnet.private",
      "children": [
        "cache_a",
        "aurora_w"
      ]
    },
    {
      "op": "createFrame",
      "id": "data_b",
      "title": "Private subnet (data)",
      "containerType": "aws.subnet.private",
      "children": [
        "aurora_r",
        "cache_b"
      ]
    },
    {
      "op": "createNode",
      "id": "users",
      "nodeType": "actor",
      "label": "Customers",
      "icon": "aws:users"
    },
    {
      "op": "createNode",
      "id": "route53",
      "nodeType": "service",
      "label": "Amazon Route 53",
      "icon": "aws:route53"
    },
    {
      "op": "createNode",
      "id": "cloudfront",
      "nodeType": "service",
      "label": "Amazon CloudFront",
      "icon": "aws:cloudfront"
    },
    {
      "op": "createNode",
      "id": "waf",
      "nodeType": "service",
      "label": "AWS WAF",
      "icon": "aws:waf"
    },
    {
      "op": "createNode",
      "id": "igw",
      "nodeType": "service",
      "label": "Internet gateway",
      "icon": "aws:internet-gateway"
    },
    {
      "op": "createNode",
      "id": "alb",
      "nodeType": "service",
      "label": "Application Load Balancer",
      "icon": "aws:application-load-balancer"
    },
    {
      "op": "createNode",
      "id": "nat_a",
      "nodeType": "service",
      "label": "NAT gateway",
      "icon": "aws:nat-gateway"
    },
    {
      "op": "createNode",
      "id": "nat_b",
      "nodeType": "service",
      "label": "NAT gateway",
      "icon": "aws:nat-gateway"
    },
    {
      "op": "createNode",
      "id": "svc_a",
      "nodeType": "service",
      "label": "Bookings API task",
      "icon": "aws:ecs-task"
    },
    {
      "op": "createNode",
      "id": "svc_b",
      "nodeType": "service",
      "label": "Bookings API task",
      "icon": "aws:ecs-task"
    },
    {
      "op": "createNode",
      "id": "cache_a",
      "nodeType": "database",
      "label": "ElastiCache primary",
      "icon": "aws:elasticache"
    },
    {
      "op": "createNode",
      "id": "aurora_w",
      "nodeType": "database",
      "label": "Aurora writer",
      "icon": "aws:aurora"
    },
    {
      "op": "createNode",
      "id": "aurora_r",
      "nodeType": "database",
      "label": "Aurora reader",
      "icon": "aws:aurora"
    },
    {
      "op": "createNode",
      "id": "cache_b",
      "nodeType": "database",
      "label": "ElastiCache replica",
      "icon": "aws:elasticache"
    },
    {
      "op": "createNode",
      "id": "cognito",
      "nodeType": "service",
      "label": "Amazon Cognito",
      "icon": "aws:cognito"
    },
    {
      "op": "createNode",
      "id": "s3_assets",
      "nodeType": "objectStorage",
      "label": "S3 web assets",
      "icon": "aws:s3"
    },
    {
      "op": "createNode",
      "id": "s3_uploads",
      "nodeType": "objectStorage",
      "label": "S3 uploads",
      "icon": "aws:s3"
    },
    {
      "op": "createNode",
      "id": "cloudwatch",
      "nodeType": "service",
      "label": "Amazon CloudWatch",
      "icon": "aws:cloudwatch"
    },
    {
      "op": "createNode",
      "id": "sqs",
      "nodeType": "queue",
      "label": "Amazon SQS",
      "icon": "aws:sqs",
      "frame": "region"
    },
    {
      "op": "createNode",
      "id": "worker",
      "nodeType": "service",
      "label": "AWS Lambda worker",
      "icon": "aws:lambda",
      "frame": "region"
    },
    {
      "op": "createEdge",
      "id": "e_dns",
      "from": {
        "elementId": "users"
      },
      "to": {
        "elementId": "route53"
      },
      "label": "DNS"
    },
    {
      "op": "createEdge",
      "id": "e_https",
      "from": {
        "elementId": "users"
      },
      "to": {
        "elementId": "cloudfront"
      },
      "label": "HTTPS"
    },
    {
      "op": "createEdge",
      "id": "e_signin",
      "from": {
        "elementId": "users"
      },
      "to": {
        "elementId": "cognito"
      },
      "label": "sign in"
    },
    {
      "op": "createEdge",
      "id": "e_waf",
      "from": {
        "elementId": "waf"
      },
      "to": {
        "elementId": "cloudfront"
      },
      "style": {
        "dash": [
          6,
          4
        ]
      },
      "endpoints": {
        "endArrow": "none"
      }
    },
    {
      "op": "createEdge",
      "id": "e_static",
      "from": {
        "elementId": "cloudfront"
      },
      "to": {
        "elementId": "s3_assets"
      },
      "label": "static files"
    },
    {
      "op": "createEdge",
      "id": "e_api",
      "from": {
        "elementId": "cloudfront"
      },
      "to": {
        "elementId": "igw"
      },
      "label": "/api/*"
    },
    {
      "op": "createEdge",
      "id": "e_igw",
      "from": {
        "elementId": "igw"
      },
      "to": {
        "elementId": "alb"
      }
    },
    {
      "op": "createEdge",
      "id": "e_alb_a",
      "from": {
        "elementId": "alb"
      },
      "to": {
        "elementId": "svc_a"
      }
    },
    {
      "op": "createEdge",
      "id": "e_alb_b",
      "from": {
        "elementId": "alb"
      },
      "to": {
        "elementId": "svc_b"
      }
    },
    {
      "op": "createEdge",
      "id": "e_cache_a",
      "from": {
        "elementId": "svc_a"
      },
      "to": {
        "elementId": "cache_a"
      }
    },
    {
      "op": "createEdge",
      "id": "e_sql_a",
      "from": {
        "elementId": "svc_a"
      },
      "to": {
        "elementId": "aurora_w"
      }
    },
    {
      "op": "createEdge",
      "id": "e_sql_b",
      "from": {
        "elementId": "svc_b"
      },
      "to": {
        "elementId": "aurora_w"
      },
      "label": "writes"
    },
    {
      "op": "createEdge",
      "id": "e_read_b",
      "from": {
        "elementId": "svc_b"
      },
      "to": {
        "elementId": "aurora_r"
      },
      "label": "reads"
    },
    {
      "op": "createEdge",
      "id": "e_cache_b",
      "from": {
        "elementId": "svc_b"
      },
      "to": {
        "elementId": "cache_b"
      }
    },
    {
      "op": "createEdge",
      "id": "e_repl_db",
      "from": {
        "elementId": "aurora_w"
      },
      "to": {
        "elementId": "aurora_r"
      },
      "label": "replication",
      "style": {
        "dash": [
          6,
          4
        ]
      }
    },
    {
      "op": "createEdge",
      "id": "e_repl_cache",
      "from": {
        "elementId": "cache_a"
      },
      "to": {
        "elementId": "cache_b"
      },
      "label": "replication",
      "style": {
        "dash": [
          6,
          4
        ]
      }
    },
    {
      "op": "createEdge",
      "id": "e_logs",
      "from": {
        "elementId": "vpc"
      },
      "to": {
        "elementId": "cloudwatch"
      },
      "label": "logs, metrics"
    },
    {
      "op": "createEdge",
      "id": "e_upload",
      "from": {
        "elementId": "svc_b"
      },
      "to": {
        "elementId": "s3_uploads"
      },
      "label": "originals"
    },
    {
      "op": "createEdge",
      "id": "e_enqueue",
      "from": {
        "elementId": "svc_b"
      },
      "to": {
        "elementId": "sqs"
      },
      "label": "enqueue"
    },
    {
      "op": "createEdge",
      "id": "e_trigger",
      "from": {
        "elementId": "sqs"
      },
      "to": {
        "elementId": "worker"
      },
      "label": "invokes"
    },
    {
      "op": "createEdge",
      "id": "e_write",
      "from": {
        "elementId": "worker"
      },
      "to": {
        "elementId": "s3_uploads"
      },
      "label": "thumbnails"
    }
  ]
}

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

Pull request 412 adds an SQS queue and a Lambda worker that resizes uploaded photos. Five elements are new: the queue, the worker, and the edges from the Bookings API task to the queue, from the queue to the worker and from the worker to the uploads bucket. The compare lists the Region as changed because the two services joined it, and the uploads bucket because it moved down the Region's column to make room. The colored image the REST image endpoint draws of revision 2 (not the plain pair shown here) marks only the five new elements, in green: the Region kept its title and border, and only the bucket's place changed. Reviewers see this list and both revisions on the pull request before anyone runs terraform apply.

  • Revision 1 → 2
  • +5 added
  • -0 removed
  • ~2 changed
Before · revision 1
AWS architecture diagram from Terraform - revision 1

Open full size of revision 1

After · revision 2
AWS architecture diagram from Terraform - revision 2

Open full size of revision 2

+ Added

  • sqs
  • worker
  • e_enqueue
  • e_trigger
  • e_write

~ Changed

  • region
  • s3_uploads

Raw compare response

{
  "id": "dgm_UFEpBsTVBkmF",
  "from": 1,
  "to": 2,
  "added": [
    "sqs",
    "worker",
    "e_enqueue",
    "e_trigger",
    "e_write"
  ],
  "changed": [
    "region",
    "s3_uploads"
  ],
  "removed": [],
  "scene": [],
  "scenario": "Pull request 412 adds an SQS queue and a Lambda worker that resizes uploaded photos. Five elements are new: the queue, the worker, and the edges from the Bookings API task to the queue, from the queue to the worker and from the worker to the uploads bucket. The compare lists the Region as changed because the two services joined it, and the uploads bucket because it moved down the Region's column to make room. The colored image the REST image endpoint draws of revision 2 (not the plain pair shown here) marks only the five new elements, in green: the Region kept its title and border, and only the bucket's place changed. Reviewers see this list and both revisions on the pull request before anyone runs terraform apply."
}

Agent resources

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

  • aws-architecture-from-terraform.scene.json Canonical DSP scene Open
  • aws-architecture-from-terraform.ops.json Typed-operation envelope that builds the scene Open
  • aws-architecture-from-terraform.workflow.json Structured agent workflow (goal, inputs, outputs, steps) Open
  • aws-architecture-from-terraform.diff.json Sample diagram_history compare response Open
  • aws-architecture-from-terraform.svg Rendered diagram: revision 2 as Zindex saved it Open
  • aws-architecture-from-terraform.before.svg Revision diff's before picture: revision 1 as Zindex saved it Open
  • aws-architecture-from-terraform.md Agent-readable markdown summary Open
  • /examples/index.json Manifest of all examples (cross-linked) Open