# Public-facing interfaces diagram from Terraform, gateway routes and ingress
> An agent reads a store's Terraform, gateway routes, service specs and ingress files. It saves an architecture diagram of what they open to the internet: who calls in, what each path reaches and how it's authenticated. Asked again after a change, it updates the same diagram.
## Metadata
- **Diagram family**: `architecture`
- **Source**: Terraform, gateway routes, OpenAPI specs and Kubernetes ingress
- **Workflow types**: scan, generate, update, diff, render
- **Audience**: security, platform, developer, agent
- **MCP tools**: `diagram_find`, `diagram_create`, `diagram_get`, `diagram_edit`, `diagram_history`, `diagram_render`
- **HTTP endpoints**:
  - `POST /v1/diagrams`
  - `GET /v1/diagrams/{id}`
  - `POST /v1/diagrams/{id}/revisions`
  - `GET /v1/diagrams/{id}/compare`
  - `GET /v1/diagrams/{id}/render`
---
---

## What this example shows

A person asks their coding agent, before a security review: "Map every public-facing interface across our repositories: the Terraform, the gateway routes and the ingress." The agent reads an online store's Terraform, gateway routes, service specs and Kubernetes ingress files. It saves an architecture diagram of what they open.

Callers sit on the left: customers, partner apps, the payment provider and staff on the VPN. Each path into the "Open to the internet" frame is labeled with how it gets in: the port at the edge, the host an ingress matches, or a gateway route with its auth. The bucket policy's public `avatars/*` prefix puts the uploads bucket in that frame too. A dashed red line from the customers marks it: the one path that skips the WAF and the load balancer and needs no credentials. Revision 2 records the review's fix, which closes that prefix, and the **Revision diff** panel below shows both revisions and the compare.

## When to use it

Before a security review, a penetration test or an audit that asks what faces the internet. Use it when the answer is spread across Terraform, gateway config, service specs and ingress files in several repositories. The diagram is saved in the team's workspace, so everyone in it opens the same one; a share link shows its images to a reviewer outside it. When the files change, the person asks again, and the agent updates the same diagram instead of drawing a new one.

## What the agent does

The agent turns what the files grant into a scene. Each caller, and each thing that answers or stores, is a node in one of three frames: the internet, what is open to it, and what is private. Each path is an edge, labeled with its port, host or route and its auth. Listeners, security groups, DNS records and IAM policies become edges and labels, not nodes.

The agent saves the scene with `diagram_create` and the key `public-interfaces`. The engine places every node and routes every edge, so the agent writes no coordinates.

After the review, the team removes the public read on `avatars/*`, and the person asks the agent again. The agent reads the change and sends one `deleteElement` for the dashed line with `diagram_edit`. It records a revision whose message names the fix; every other element keeps its ID, and no node moves. `diagram_history` with `compare` lists the removed edge, and `diagram_render` gives image links for the review notes.

## What the output includes

- One architecture diagram of the store's public interfaces, on a dark canvas, that the agent edits rather than redraws when asked again.
- Each path the files open to the internet, labeled with how it is authenticated. The one path past the WAF and the load balancer that needs no credentials, a public bucket prefix, is dashed in revision 1.
- A revision for each change the agent is asked to record, its message naming the change, such as the fix that closes the public prefix.
- A compare JSON listing what each change adds, changes and removes, and SVG and PNG links to each revision.

## What this example does not aim to do

The diagram shows what the agent found in the files it read, not what is deployed. A resource created by hand, a rule changed in a console or a repository the agent wasn't pointed at isn't in it. This example doesn't scan ports, test authentication or rate a risk. It gives the review a shared picture of what the code opens, to start from.
## Agent workflow
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
**Steps**

1. **Read what the code opens** - 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.

2. **Find the diagram** - 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`_

3. **Save the diagram** - 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: `POST /v1/diagrams`_

4. **Read the diagram's current revision** - 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: `GET /v1/diagrams/${SCENE_ID}`_

5. **Turn the change into operations** - 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.

6. **Save the change as a revision** - 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: `POST /v1/diagrams/${SCENE_ID}/revisions`_

7. **List what the change adds and removes** - 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: `GET /v1/diagrams/${SCENE_ID}/compare?from=${BASE}&to=${NEW_REVISION}`_

8. **Render the revision** - 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: `GET /v1/diagrams/${SCENE_ID}/render`_
## Agent prompt

Drop this into a system prompt for an MCP-connected agent.

```
Map every public-facing interface across our repositories: the Terraform, the gateway routes and the ingress. Mark what's open to the internet. It's for Thursday's security review.

You draw this diagram from the store's code. The files are the Terraform in `infra/`, the API gateway's routes in `gateway/routes.yaml`, each service's spec in `services/*/openapi.yaml` and the Kubernetes ingress files in `k8s/ingress/`. When you're asked again after they change, you update the same diagram.

The reviewers read the diagram as a list of what a request from the internet can reach and how each entry point is authenticated. Draw what the files grant and nothing you can't point to in them. The diagram's key is `public-interfaces`; once it exists, its Zindex ID is `${SCENE_ID}`.

How to draw it:
- `diagramFamily: "architecture"`, with three frames. `internet` ("Internet") holds who calls in. `open` ("Open to the internet") holds everything a request from the internet reaches, through the edge or straight past it. `private` ("Private") holds what only the cluster or the VPN reaches. Outline `open` in red (`style: { stroke: "#c0544e" }`), so it reads first.
- A node for each caller from outside and each thing that answers or stores: the WAF, the public load balancer, the gateway, each service behind an ingress or a gateway route, workers, the database and buckets. DNS records, certificates, security groups, listeners and IAM policies aren't nodes. They tell you the edges and what's open. Write no `layout`: the engine places every node and routes every edge.
- An edge from caller to callee for each path the files grant. Label each edge into or within `open` with how the internet reaches it: the port at the edge (`HTTPS 443`), the host an ingress matches (`app.* · session`), or a gateway route with its auth (`/v1/* · API key`, `/oauth/* · none`).
- A public grant skips the WAF and the load balancer and needs no credentials, like a bucket policy's public prefix. Its target goes in `open`, with a dashed red edge (`style: { dash: [6, 4], stroke: "#c0544e", textColor: "#c0544e" }`) from the callers, labeled with its path. A bucket that browsers reach with signed URLs is in `open` too, with a solid edge from the service that signs them.
- Between your own services, draw queues and each service's database access.
- Short, stable IDs (`waf`, `gateway`, `public_api`), and a brief that states these conventions, so the next agent keeps them.

Steps:

1. Call `diagram_find({ query: "public-interfaces" })` and take the result whose key is `public-interfaces`. If there is one, use its ID and go to step 2. If there is none, build the scene from the files, call `diagram_create({ key: "public-interfaces", scene, message })` and use the ID it returns. Fix anything the save's `warnings` name with a follow-up edit, then call `diagram_render` as in step 5 and stop.

2. Call `diagram_get({ id: "${SCENE_ID}" })`. Read the current revision number from the outline's first line; call it `BASE`. Compare the outline's elements, with their IDs and labels, to what the files grant now; a long outline ends with `nextCursor` for the next page.

3. Turn what changed into typed operations. A new service is a `createNode` with `frame` set to the frame it belongs in. A new route or grant is a `createEdge`, a closed route or grant a `deleteElement`, and a route whose auth changed an `updateEdge` with the new label. Reuse the diagram's IDs.

4. Call `diagram_edit({ id: "${SCENE_ID}", baseRevision: BASE, message, ops })` with a message that names the change, such as `Close the public avatars prefix: avatars load through signed URLs`. If it returns `REVISION_CONFLICT`, someone saved a newer revision after you read it. The error lists what changed, so plan the edit again against the revision it names.

5. Call `diagram_history({ id: "${SCENE_ID}", compare: { from: BASE, to: <the new revision> } })` for what the change added, changed and removed. Then call `diagram_render({ id: "${SCENE_ID}" })` for SVG and PNG links, valid for 7 days, for the review notes.

Hard rules: draw what the files show; when a file you need isn't there, say so rather than guess. If a change opens, closes or re-authenticates nothing, say so and record nothing. Never redraw the diagram or recreate an element to change it; the IDs carry its history. Never give a node a `layout`.
```
## Validation

Captured `POST /v1/diagrams/validate` response: **valid** (0 errors, 0 warnings)

_The scene validates with no errors or warnings._
## Resources
- **Canonical scene**: [/examples/public-interfaces-for-security-review.scene.json](/examples/public-interfaces-for-security-review.scene.json) (revision 2's scene, without the node positions Zindex saved with it)
- **Operations envelope**: [/examples/public-interfaces-for-security-review.ops.json](/examples/public-interfaces-for-security-review.ops.json)
- **Workflow recipe**: [/examples/public-interfaces-for-security-review.workflow.json](/examples/public-interfaces-for-security-review.workflow.json)
- **Revision diff**: [/examples/public-interfaces-for-security-review.diff.json](/examples/public-interfaces-for-security-review.diff.json)
- **Rendered SVG**: [/examples/public-interfaces-for-security-review.svg](/examples/public-interfaces-for-security-review.svg) (revision 2 as Zindex saved it: its edit moved no placed node `.diff.json` doesn't list; previewing `.scene.json` lays every node out from scratch, so nodes can land elsewhere)
- **Before SVG**: [/examples/public-interfaces-for-security-review.before.svg](/examples/public-interfaces-for-security-review.before.svg) (revision 1 as Zindex saved it, the revision diff's before picture)
- **Human page**: [/examples/public-interfaces-for-security-review/](/examples/public-interfaces-for-security-review/)
- **Manifest**: [/examples/index.json](/examples/index.json)
## Related examples

- [/examples/aws-architecture-from-terraform/](/examples/aws-architecture-from-terraform/)
- [/examples/compliance-pii-flow/](/examples/compliance-pii-flow/)
- [/examples/api-dependency-map/](/examples/api-dependency-map/)