{
  "schemaVersion": "1.0",
  "id": "gcp-architecture-from-terraform",
  "title": "Google Cloud architecture diagram from Terraform",
  "slug": "gcp-architecture-from-terraform",
  "diagramFamily": "architecture",
  "goal": "Keep a team's Google Cloud diagram in step with its Terraform: drawn once from the default branch, then one revision per infrastructure pull request, posted on the pull request 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, listings-gcp-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 Google Cloud's groups and product cards, 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, `listings-gcp-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 and the conventions in its README. Each resource that runs or stores something becomes a node with its `gcp:` icon, in the innermost group the README places it in. Logging and Monitoring are one card, and the NAM4 buckets one stacked card. Health checks, backend services, URL maps, certificates, service accounts and role bindings 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, a brief that states these conventions, and the scene with the nodes and edges from `read_terraform`. Write `diagramFamily: \"architecture\"` and a frame per Google Cloud group with its `containerType`, each subnet listing its web tier, internal load balancer, app tier, Memorystore instance and database tier in that order. A `gcp.vpc` spans both subnets and a `gcp.zone` spans each zone's nodes. Leave `layout`, `shape` and `fill` off, except the standby's gray `style.fill` (`#DADCE0`), and give the buckets card `style.multiple: true`. The engine arranges the groups and draws each node as Google's card. If the save's `warnings` carry `GCP_GROUP_UNTYPED` or `GCP_GROUP_NESTING`, act on the group each one names, as 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: a topic an app tier's metadata names, a function's trigger, a role on a bucket, a backend service's instance groups.",
      "mcp": null,
      "http": null
    },
    {
      "id": "compute_ops",
      "label": "Compute the operation batch",
      "description": "A new resource becomes a `createNode` with `frame` set to its group (PR 587's topic and function join `region_c1`), except a bucket in NAM4, which the buckets card stands for. A new VM also needs an `updateFrame` on its `gcp.zone` with the whole `spans`, or, for a new zone, a `createFrame` with `containerType` `gcp.zone`, its name as `title` and `spans` listing the VM. New connections are `createEdge`, destroyed resources `deleteElement` and renamed ones `updateNode`. Reuse the diagram's IDs and write no `layout`. A change that adds, removes or connects no drawn resource (machine types, resource labels, 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; the new revision is PR_REVISION. A batch that changes nothing answers `noop: true` and makes no revision. In PR 587 the topic and the function take a row below us-central1's subnet, and the app tier's line to the topic opens a gap between two zone columns in both Regions. What lies past each growth moves by it, and the compare lists what moved.",
      "mcp": "diagram_edit",
      "http": {
        "method": "POST",
        "path": "/v1/diagrams/${SCENE_ID}/revisions",
        "exampleRequest": "{\n  \"baseRevision\": 1,\n  \"message\": \"PR 587: make listing thumbnails in a Cloud Run function fed by Pub/Sub\",\n  \"ops\": [\n    {\n      \"op\": \"createNode\",\n      \"id\": \"photos_topic\",\n      \"nodeType\": \"queue\",\n      \"label\": \"Listing photos\",\n      \"icon\": \"gcp:pubsub\",\n      \"frame\": \"region_c1\"\n    },\n    {\n      \"op\": \"createNode\",\n      \"id\": \"thumbnailer\",\n      \"nodeType\": \"service\",\n      \"label\": \"Thumbnail worker\",\n      \"icon\": \"gcp:cloud-run-functions\",\n      \"frame\": \"region_c1\"\n    },\n    {\n      \"op\": \"createEdge\",\n      \"id\": \"e_publish\",\n      \"from\": {\n        \"elementId\": \"app_c1\"\n      },\n      \"to\": {\n        \"elementId\": \"photos_topic\"\n      },\n      \"label\": \"Photo URLs\"\n    },\n    {\n      \"op\": \"createEdge\",\n      \"id\": \"e_trigger\",\n      \"from\": {\n        \"elementId\": \"photos_topic\"\n      },\n      \"to\": {\n        \"elementId\": \"thumbnailer\"\n      },\n      \"label\": \"Triggers\"\n    },\n    {\n      \"op\": \"createEdge\",\n      \"id\": \"e_thumbs\",\n      \"from\": {\n        \"elementId\": \"thumbnailer\"\n      },\n      \"to\": {\n        \"elementId\": \"storage\"\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 587 that is the topic, the function and their three edges added. As changed, it lists the Region they joined and the cards the engine moved 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 card that only moved, or a group that only gained members, is drawn as unchanged, though the compare lists it as changed. `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"
      }
    }
  ]
}