# Layered architecture diagram from a codebase
> Let an agent draw a codebase's layers as a stack of rows from its package manifests. It lists each layer and its cards and writes no coordinates. The engine stacks the layers in the order listed, orders each row and runs the lines between them, those that skip a layer included.
## Metadata
- **Diagram family**: `architecture`
- **Source**: Package manifests / architecture layer map
- **Workflow types**: scan, generate, update, validate, render
- **Audience**: developer, platform, agent
- **MCP tools**: `diagram_find`, `diagram_create`, `diagram_get`, `diagram_edit`, `diagram_render`
- **HTTP endpoints**:
  - `POST /v1/diagrams`
  - `GET /v1/diagrams/{id}`
  - `POST /v1/diagrams/{id}/revisions`
  - `GET /v1/diagrams/{id}/render`
---
---

## What this example shows

A bike-share platform's codebase drawn as five layers, top to bottom: clients, edge, services, data and external providers. The agent listed each layer and the cards in it, and wrote no coordinates, no layout on a layer or a card, and no anchors. The engine stacked the layers as rows in the order listed and put every card in its layer's frame. It gave the five layers one width and left a gap between them for the lines.

Payments is a sub-group inside Services, and its two runners stay together in the row. Every line runs from caller to callee. The Charge runner and the Notice sender each call a provider, so their two lines skip the Data layer. In this drawing each runs between the Data layer's cards and crosses every layer border at a right angle. The one label, `Trip events`, names the line from the Trip service to the event bus.

## When to use it

When a codebase is arranged in layers and the diagram should say which layer each part belongs to. The agent knows a package's layer and whether it is a service or a store, and the engine places it in that layer's row. When the order should follow the lines instead, draw without layers and the engine places the nodes from the edges ([Layout engine](/docs/reference/layout-engine/)).

## What the agent does

The agent reads `ARCHITECTURE.md` for the layers and their order, and each package's `package.json` for its layer and the packages it calls. It writes a frame for each layer with `containerType: "layer"`, lists the layers top to bottom, lists each card in its layer, and writes an edge for each call. It saves the diagram with `diagram_create`, then reads the warnings the save returns.

When a package is added, the agent sends `createNode` with `frame` set to its layer and a `createEdge` for each call. The card stands in that layer's row, and a layer that grows moves the layers after it along ([Layers](/docs/reference/layout-engine/#layers)). A package that moves to another layer is an `updateNode` with a new `frame`.

## What the output includes

- A layered architecture diagram: five layer frames of one width, 19 cards with Lucide icons, a sub-group and 21 lines.
- The agent's prompt, the typed operations that build the scene, and the scene itself, which has no `layout` or `anchor` anywhere.
- A revision for each change to the codebase, its message naming the package.
- The limits ([Layers](/docs/reference/layout-engine/#layers)): the order of the layers comes from the agent's listing and never from the lines, and the engine orders the cards of a row itself. Only the scene's first stack is arranged, in an architecture diagram or one without a family, outside any pool, lane or fragment. In an AWS or Google Cloud diagram, the stack goes in a generic frame of its own, or a cloud boundary that holds no Region. A layer written with a `layout` of its own keeps that box and draws as a plain frame, with no warning.
## Agent workflow
Draw a codebase's layered architecture from its package manifests as a stack of layers the engine arranges, then change the saved diagram when a package is added, moved, renamed or removed.
**Inputs**

- ARCHITECTURE.md, which names the layers in the order they stack
- Every package.json: its layer, its label and the packages it calls
- The diagram's Zindex key, bikeshare-layers, or its ID from .zindex.json (long-lived, never recreated)
- A Zindex API key, or an MCP client signed in to Zindex
**Outputs**

- A diagram of five layers, listed top to bottom, each holding its packages as cards, with a sub-group and a line from each caller to its callee
- A revision for each change to the codebase, its message naming the package
- SVG and PNG links to a revision, and an SVG committed next to ARCHITECTURE.md
**Steps**

1. **Find the architecture diagram** - Call `diagram_find` with the key `bikeshare-layers` and take the result whose key it is, or read the ID from `.zindex.json`. If the diagram exists, go to `read_current`. Over REST, `GET /v1/diagrams/{key}` answers 404 `NOT_FOUND` when there is none yet.
   _MCP: `diagram_find` · HTTP: `GET /v1/diagrams/${SCENE_ID}`_

2. **Read the layers and the packages** - Read ARCHITECTURE.md for the layers and their order, then every `package.json` for its `layer`, its `label` and its `calls`. Each package becomes a node with a `nodeType`: `database` for a store, `queue` for the bus, `externalSystem` for a provider and `service` for the rest. Its `icon` is a Lucide key written `lucide:<name>`, and its `id` is the package's name. Packages that ARCHITECTURE.md groups under a heading become a sub-group, a frame with no `containerType`. Each entry in `calls` becomes an edge from caller to callee, and a call to a layer further down is one edge like any other.

3. **Save the first drawing** - Call `diagram_create` with the key, a message and the scene. Write `diagramFamily: "architecture"` and a frame for each layer with `containerType: "layer"`, listed top to bottom in the order ARCHITECTURE.md gives, each listing its cards in `children`. Leave `layout` off the layers, the sub-group and the nodes, write no anchors, and leave `layoutStrategy.direction` off so the stack runs top to bottom. The engine stacks the layers as rows in the order listed, all of one width. It fits each layer around its cards and orders each row to cut the crossings between layers, though not always to the fewest. It takes the order of the layers from the listing and never from the lines, and it arranges the scene's first stack only. A layer written with a `layout` gets no warning and draws as a plain frame: write it without one, or send `autoLayout` without `elements`, which places every card again and takes the layout off every frame but a pool, lane or fragment.
   _MCP: `diagram_create` · HTTP: `POST /v1/diagrams`_

4. **Fix what the warnings report** - The save's `warnings` list what checking and drawing the diagram noticed, each with a `code`, the `element` when there is one and a one-line `fix`. `LAYER_NOT_ARRANGED` names a layer drawn as a plain frame: list all the layers of the stack together, at the root or in one frame, outside any pool, lane or fragment, and in an AWS or Google Cloud diagram put the stack in a generic frame of its own. `ICON_NOT_FOUND` names an icon key that doesn't exist: set one that does with `updateNode`.

5. **Read the diagram's current revision** - When a package changes, call `diagram_get`. The outline's first line gives the current revision. Each element line after it gives an ID, a type and a label, with each layer's cards indented under it, so you reuse the IDs the diagram already has.
   _MCP: `diagram_get` · HTTP: `GET /v1/diagrams/${SCENE_ID}`_

6. **Compute the operations** - A new package is a `createNode` with `frame` set to its layer's ID, or its sub-group's, and a `createEdge` for each entry in its `calls`. A package that moves layers is an `updateNode` with the new `frame`, a renamed one an `updateNode` with its `label`, and a removed one a `deleteElement`. A new layer is a `createFrame` with `containerType: "layer"` and a `title`, and it goes after the others; set `frame` when a frame lists the layers. No operation puts a layer between two others: `deleteElement` each layer, then `createFrame` each again in the new order. Give each `containerType: "layer"`, its cards and sub-groups in `children`, and `frame` set to the frame that lists the layers, if one does. Then send `autoLayout` without `elements`.

7. **Save the change as one edit** - One `diagram_edit` with `baseRevision` set to the revision you read and a `message` naming the package, such as `add loyalty service to services`. The card stands in its layer's row, and no saved card moves except to make room. If the diagram changed after you read it, the call returns `REVISION_CONFLICT` with what changed; plan again against the new revision. An edit that changes nothing returns `noop: true` and makes no revision.
   _MCP: `diagram_edit` · HTTP: `POST /v1/diagrams/${SCENE_ID}/revisions`_

8. **Render the revision** - Get SVG and PNG links to the revision; they work without a key for 7 days. Download the SVG and commit it next to ARCHITECTURE.md, since the links expire. Each revision's image is drawn once and kept, and prints its address, `zindex.ai/d/<id>@<revision>`, and date.
   _MCP: `diagram_render` · HTTP: `GET /v1/diagrams/${SCENE_ID}/render`_
## Agent prompt

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

```
You keep the architecture diagram of a bike-share platform's monorepo in Zindex, drawn as a stack of layers. ARCHITECTURE.md names the five layers, top to bottom: `clients`, `edge`, `services`, `data` and `providers`. Each package's `package.json` has a `layer` field naming one of them, a `label` and a `calls` list of the packages it calls. You draw the diagram once from the default branch, then change it when a package is added, moved, renamed or removed.

The diagram's Zindex ID is `${SCENE_ID}` and its key is `bikeshare-layers`. Revisions are permanent, so change the diagram with edits and never recreate it.

How to draw it:
- `diagramFamily: "architecture"`, and a frame for each layer with `containerType: "layer"` and a `title`, listed in the order ARCHITECTURE.md gives them, top to bottom. The listing sets the order: a stack listed bottom to top draws bottom to top.
- Each layer lists in its `children` the packages whose `layer` is that layer. A frame with no `containerType` among them is a sub-group: it lists its own cards and stays whole in the layer's row. Use one for the packages ARCHITECTURE.md groups under a heading, here `Payments`.
- A node for each package. Use the package's name as its `id`, and keep that `id` if the package is renamed. Give it the `label` from `package.json`, an `icon` such as `lucide:database`, and a `nodeType`: `database` for a store, `queue` for the bus, `externalSystem` for a provider and `service` for the rest.
- An edge from caller to callee for each entry in `calls`. An edge can skip a layer: write one edge from a service to a provider, and the engine runs it through the layer in the way, across each border at a right angle. Label an edge only when its two ends don't say what flows, such as `Trip events`.
- Write no `layout` on a layer, a sub-group or a node, and no `anchor` on an edge. Leave `layoutStrategy.direction` off, so the stack runs top to bottom; `LR` and `RL` make the layers columns, and `BT` runs the stack upward.

With those left off, the engine stacks the layers as rows in the order listed, all of one width. It fits each layer around its cards, orders each row to cut the crossings between layers, and runs the lines through the layers and the gaps between them.

What the engine doesn't do:
- It takes the order of the layers from your listing, never from the lines, so list them as ARCHITECTURE.md does.
- It orders the cards of a row to cut the crossings between layers and doesn't promise the fewest, so don't rely on your listing for their order from left to right. A layer wider than 1,400 px wraps into rows of near-equal count.
- It arranges one stack, the first in the scene, in an architecture diagram or one without a family. In an AWS or Google Cloud diagram, it arranges the stack only inside a generic frame of its own, or a cloud boundary that holds no Region. List all five layers together, at the root or in one frame's `children`. A layer in a second stack, or inside a pool, lane or fragment, draws as a plain frame and gets `LAYER_NOT_ARRANGED`.
- A layer with a `layout` of its own isn't arranged. It keeps that box and draws as a plain frame, and the API returns no warning for it. To arrange it, write the layer without `layout`, or send `autoLayout` without `elements`, which takes its layout off and places every card again. `diagram_get` with `view: "dsp"` shows a layer's `layout`.
- A card in no layer isn't in a row, and an edit that adds one places it by the general rules. List every package in its layer.

Steps:

1. If you don't have the diagram's ID yet, call `diagram_find({ query: "bikeshare-layers" })` and take the result whose key is `bikeshare-layers`. If there is none, read ARCHITECTURE.md and every `package.json`, build the scene as above, and call `diagram_create({ key: "bikeshare-layers", scene, message })` with a brief that states these conventions. Use the ID it returns. Act on every warning in the save's `warnings`:
   - `LAYER_NOT_ARRANGED` names a layer drawn as a plain frame. List all the layers of the stack together, at the root or in one frame, outside any pool, lane or fragment. In an AWS or Google Cloud diagram, put the stack in a generic frame of its own.
   - `ICON_NOT_FOUND`: set an icon key that exists, such as `lucide:database`, with `updateNode`. The warning's `fix` names close ones.

2. When a package changes, call `diagram_get({ id: "${SCENE_ID}" })`. Read the current revision from the outline's first line. Each element line after it gives an ID, a type and a label, with each layer's cards indented under it: a layer's type is `layer` and a sub-group's is `frame`. Keep the revision for `baseRevision` and reuse the IDs.

3. Turn each change into edits:
   - A new package is a `createNode` with `frame` set to its layer's ID, or to its sub-group's ID when ARCHITECTURE.md groups it, and a `createEdge` for each entry in its `calls`. It stands in that layer's row. No saved card moves except to make room: a layer that gains a row or a taller card grows, and the layers after it move along. A card added to a sub-group makes it grow. When it grows wider, the cards to its right in the row move over. When it grows taller, its layer grows.
   - A package that moves to another layer is an `updateNode` with `frame` set to the new layer's ID. A renamed one is an `updateNode` with its new `label`. A removed one is a `deleteElement`.
   - A new layer is a `createFrame` with `containerType: "layer"` and a `title`, and it goes after the others. When a frame lists the layers, set `frame` to it, or the layer isn't part of the stack.
   - No operation puts a layer between two others. To insert one, send one edit with three steps. First, `deleteElement` each of the stack's layers. Second, `createFrame` each again in the new order. Give each `containerType: "layer"`, its `title`, its cards and sub-groups in `children`, and `frame` set to the frame that lists the layers, if one does. Third, `autoLayout` without `elements`, which places every card again. Without the `autoLayout` the layers draw in the old order.

4. Call `diagram_edit({ id: "${SCENE_ID}", baseRevision, message, ops })` with one batch and a `message` that names the package, such as `add loyalty service to services`. If it returns `REVISION_CONFLICT`, someone changed the diagram after you read it: the error lists what changed, so plan again. An edit that changes nothing returns `noop: true` and makes no revision.

5. Call `diagram_render({ id: "${SCENE_ID}" })`. It returns SVG and PNG links to the new revision, valid for 7 days. Download the SVG and commit it next to ARCHITECTURE.md, since the links expire.

Hard rules: write no `layout` on a layer, a sub-group or a node, and no `anchor` on an edge. Never leave a package out of its layer. Never recreate the diagram: stable IDs keep the revision history readable.
```
## Validation

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

_The scene validates with no errors or warnings._
## Resources
- **Canonical scene**: [/examples/layered-architecture-from-codebase.scene.json](/examples/layered-architecture-from-codebase.scene.json)
- **Operations envelope**: [/examples/layered-architecture-from-codebase.ops.json](/examples/layered-architecture-from-codebase.ops.json)
- **Workflow recipe**: [/examples/layered-architecture-from-codebase.workflow.json](/examples/layered-architecture-from-codebase.workflow.json)
- **Revision diff**: [/examples/layered-architecture-from-codebase.diff.json](/examples/layered-architecture-from-codebase.diff.json)
- **Rendered SVG**: [/examples/layered-architecture-from-codebase.svg](/examples/layered-architecture-from-codebase.svg)
- **Human page**: [/examples/layered-architecture-from-codebase/](/examples/layered-architecture-from-codebase/)
- **Manifest**: [/examples/index.json](/examples/index.json)
## Related examples

- [/examples/living-architecture-docs/](/examples/living-architecture-docs/)
- [/examples/aws-architecture-from-terraform/](/examples/aws-architecture-from-terraform/)
- [/examples/api-dependency-map/](/examples/api-dependency-map/)