{
  "schemaVersion": "1.0",
  "id": "aws-architecture-from-terraform",
  "title": "AWS architecture diagram from Terraform",
  "slug": "aws-architecture-from-terraform",
  "diagramFamily": "architecture",
  "goal": "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"
  ],
  "mcpTools": [
    "diagram_find",
    "diagram_create",
    "diagram_get",
    "diagram_edit",
    "diagram_history",
    "diagram_render"
  ],
  "httpEndpoints": [
    "POST /v1/diagrams",
    "GET /v1/diagrams/{id}",
    "POST /v1/diagrams/{id}/revisions",
    "GET /v1/diagrams/{id}/compare",
    "GET /v1/diagrams/{id}/render",
    "GET /v1/images/{id}@{revision}.svg"
  ],
  "steps": [
    {
      "id": "find_diagram",
      "label": "Find the architecture diagram",
      "description": "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.",
      "mcp": "diagram_find",
      "http": {
        "method": "GET",
        "path": "/v1/diagrams/${SCENE_ID}"
      }
    },
    {
      "id": "read_terraform",
      "label": "Read the Terraform on the default branch",
      "description": "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.",
      "mcp": null,
      "http": null
    },
    {
      "id": "create_diagram",
      "label": "Save the first drawing",
      "description": "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.",
      "mcp": "diagram_create",
      "http": {
        "method": "POST",
        "path": "/v1/diagrams"
      }
    },
    {
      "id": "read_current",
      "label": "Read the diagram's current revision",
      "description": "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.",
      "mcp": "diagram_get",
      "http": {
        "method": "GET",
        "path": "/v1/diagrams/${SCENE_ID}"
      }
    },
    {
      "id": "read_pull_request",
      "label": "Read the pull request's change",
      "description": "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.",
      "mcp": null,
      "http": null
    },
    {
      "id": "compute_ops",
      "label": "Compute the operation batch",
      "description": "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.",
      "mcp": null,
      "http": null
    },
    {
      "id": "record_pr_revision",
      "label": "Save the pull request as a revision",
      "description": "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.",
      "mcp": "diagram_edit",
      "http": {
        "method": "POST",
        "path": "/v1/diagrams/${SCENE_ID}/revisions",
        "exampleRequest": "{\n  \"baseRevision\": 1,\n  \"message\": \"PR 412: resize uploaded photos in a Lambda worker fed by SQS\",\n  \"ops\": [\n    {\n      \"op\": \"createNode\",\n      \"id\": \"sqs\",\n      \"nodeType\": \"queue\",\n      \"label\": \"Amazon SQS\",\n      \"icon\": \"aws:sqs\",\n      \"frame\": \"region\"\n    },\n    {\n      \"op\": \"createNode\",\n      \"id\": \"worker\",\n      \"nodeType\": \"service\",\n      \"label\": \"AWS Lambda worker\",\n      \"icon\": \"aws:lambda\",\n      \"frame\": \"region\"\n    },\n    {\n      \"op\": \"createEdge\",\n      \"id\": \"e_enqueue\",\n      \"from\": {\n        \"elementId\": \"svc_b\"\n      },\n      \"to\": {\n        \"elementId\": \"sqs\"\n      },\n      \"label\": \"enqueue\"\n    },\n    {\n      \"op\": \"createEdge\",\n      \"id\": \"e_trigger\",\n      \"from\": {\n        \"elementId\": \"sqs\"\n      },\n      \"to\": {\n        \"elementId\": \"worker\"\n      },\n      \"label\": \"invokes\"\n    },\n    {\n      \"op\": \"createEdge\",\n      \"id\": \"e_write\",\n      \"from\": {\n        \"elementId\": \"worker\"\n      },\n      \"to\": {\n        \"elementId\": \"s3_uploads\"\n      },\n      \"label\": \"thumbnails\"\n    }\n  ]\n}"
      }
    },
    {
      "id": "compare_revisions",
      "label": "Compare the default branch's revision with the pull request's",
      "description": "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.",
      "mcp": "diagram_history",
      "http": {
        "method": "GET",
        "path": "/v1/diagrams/${SCENE_ID}/compare?from=${MAIN_REVISION}&to=${PR_REVISION}"
      }
    },
    {
      "id": "render_before_after",
      "label": "Render both revisions",
      "description": "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.",
      "mcp": "diagram_render",
      "http": {
        "method": "GET",
        "path": "/v1/diagrams/${SCENE_ID}/render?revision=${MAIN_REVISION}"
      }
    },
    {
      "id": "render_colored_diff",
      "label": "Optional: one image with the changes colored",
      "description": "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.",
      "mcp": null,
      "http": {
        "method": "GET",
        "path": "/v1/images/${SCENE_ID}@${PR_REVISION}.svg?from=${MAIN_REVISION}"
      }
    },
    {
      "id": "comment_on_pr",
      "label": "Post the change on the pull request",
      "description": "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.",
      "mcp": null,
      "http": null
    },
    {
      "id": "pr_closed",
      "label": "If the pull request is closed without merging",
      "description": "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.",
      "mcp": "diagram_edit",
      "http": {
        "method": "POST",
        "path": "/v1/diagrams/${SCENE_ID}/revisions"
      }
    }
  ]
}