{
  "schemaVersion": "1.0",
  "id": "public-interfaces-for-security-review",
  "title": "Public-facing interfaces diagram from Terraform, gateway routes and ingress",
  "slug": "public-interfaces-for-security-review",
  "diagramFamily": "architecture",
  "goal": "Draw what a store's Terraform, gateway routes, service specs and ingress files open to the internet, as an architecture diagram for a security review. When asked again after those files change, record the change as a revision of the same diagram.",
  "inputs": [
    "The edge and data Terraform (infra/*.tf)",
    "The API gateway's routes (gateway/routes.yaml) and each service's OpenAPI spec (services/*/openapi.yaml)",
    "The Kubernetes ingress files (k8s/ingress/*.yaml)",
    "The diagram's Zindex key, public-interfaces (the diagram is created on the first run)",
    "An MCP client signed in to Zindex, or a Zindex API key"
  ],
  "outputs": [
    "Revision 1: who calls in, everything a request from the internet reaches and how each path is authenticated, and what stays private, laid out by the engine",
    "A revision for each change to those files that the agent is asked to record, its message naming the change",
    "A compare listing the elements each change adds, changes and removes",
    "SVG and PNG links to each revision for the review notes"
  ],
  "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"
  ],
  "steps": [
    {
      "id": "read_files",
      "label": "Read what the code opens",
      "description": "Read the Terraform, the gateway's routes, the service specs and the ingress files. Listeners, ingress hosts and gateway routes say what a request from the internet reaches and how it is authenticated. A bucket policy with a public principal is a path past the WAF and the load balancer that needs no credentials. DNS records, certificates, security groups, listeners and IAM policies aren't nodes; they tell you the edges and their labels.",
      "mcp": null,
      "http": null
    },
    {
      "id": "find_diagram",
      "label": "Find the diagram",
      "description": "Call `diagram_find` with the diagram's key, `public-interfaces`, as its query. On the first run it finds nothing, and the next step creates the diagram; on later runs it returns the diagram's ID, and you go to `read_current`.",
      "mcp": "diagram_find",
      "http": null
    },
    {
      "id": "create_diagram",
      "label": "Save the diagram",
      "description": "Save the scene with `diagram_create` and the key `public-interfaces`. Its family is `architecture`, with the frames `internet`, `open` and `private`. Each path the files grant is an edge from caller to callee; an edge into `open` is labeled with how the internet reaches it. Its `brief` states these conventions. Zindex checks the scene, lays it out and draws it, and everyone in the workspace opens the same diagram.",
      "mcp": "diagram_create",
      "http": {
        "method": "POST",
        "path": "/v1/diagrams"
      }
    },
    {
      "id": "read_current",
      "label": "Read the diagram's current revision",
      "description": "When asked again after the files change, call `diagram_get`. The outline's first line gives the current revision number (BASE), and its lines give each element with its ID and label, so you can see which IDs already exist.",
      "mcp": "diagram_get",
      "http": {
        "method": "GET",
        "path": "/v1/diagrams/${SCENE_ID}"
      }
    },
    {
      "id": "compute_ops",
      "label": "Turn the change into operations",
      "description": "A new service is a `createNode` with `frame` set to the frame it belongs in, a new route or grant a `createEdge`, a closed route or grant a `deleteElement`, and a route whose auth changed an `updateEdge` with the new label. The fix in this example is one `deleteElement`: the bucket policy's public read on `avatars/*` is gone, so the dashed edge goes, and the bucket stays in `open` because browsers still fetch from it with signed URLs.",
      "mcp": null,
      "http": null
    },
    {
      "id": "record_revision",
      "label": "Save the change as a revision",
      "description": "Call `diagram_edit` with the ops, `baseRevision` = BASE and a message that names the change. The edit is all or nothing: if an operation has errors, it returns `VALIDATION_FAILED` with an `errors` list and saves nothing. Fix the ops each error names and send the edit again. If another agent saved a newer revision after you read it, it returns `REVISION_CONFLICT` with what changed, and you plan the edit again against that revision.",
      "mcp": "diagram_edit",
      "http": {
        "method": "POST",
        "path": "/v1/diagrams/${SCENE_ID}/revisions"
      }
    },
    {
      "id": "compare_revisions",
      "label": "List what the change adds and removes",
      "description": "Call `diagram_history` with `compare: { from: BASE, to: <the new revision> }`. It lists the element IDs the change adds, changes and removes, so the review notes can say which paths from the internet opened or closed.",
      "mcp": "diagram_history",
      "http": {
        "method": "GET",
        "path": "/v1/diagrams/${SCENE_ID}/compare?from=${BASE}&to=${NEW_REVISION}"
      }
    },
    {
      "id": "render",
      "label": "Render the revision",
      "description": "Get SVG and PNG links to the new revision; they work without a key for 7 days. The image is drawn once and kept, and it prints its address, `zindex.ai/d/<id>@<revision>`, and date, so it is traceable to its revision.",
      "mcp": "diagram_render",
      "http": {
        "method": "GET",
        "path": "/v1/diagrams/${SCENE_ID}/render"
      }
    }
  ]
}