{
  "schemaVersion": "1.0",
  "id": "layered-architecture-from-codebase",
  "title": "Layered architecture diagram from a codebase",
  "slug": "layered-architecture-from-codebase",
  "diagramFamily": "architecture",
  "goal": "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"
  ],
  "mcpTools": [
    "diagram_find",
    "diagram_create",
    "diagram_get",
    "diagram_edit",
    "diagram_render"
  ],
  "httpEndpoints": [
    "POST /v1/diagrams",
    "GET /v1/diagrams/{id}",
    "POST /v1/diagrams/{id}/revisions",
    "GET /v1/diagrams/{id}/render"
  ],
  "steps": [
    {
      "id": "find_diagram",
      "label": "Find the architecture diagram",
      "description": "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": {
        "method": "GET",
        "path": "/v1/diagrams/${SCENE_ID}"
      }
    },
    {
      "id": "read_layers",
      "label": "Read the layers and the packages",
      "description": "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.",
      "mcp": null,
      "http": null
    },
    {
      "id": "create_diagram",
      "label": "Save the first drawing",
      "description": "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": {
        "method": "POST",
        "path": "/v1/diagrams"
      }
    },
    {
      "id": "check_warnings",
      "label": "Fix what the warnings report",
      "description": "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`.",
      "mcp": null,
      "http": null
    },
    {
      "id": "read_current",
      "label": "Read the diagram's current revision",
      "description": "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": {
        "method": "GET",
        "path": "/v1/diagrams/${SCENE_ID}"
      }
    },
    {
      "id": "compute_ops",
      "label": "Compute the operations",
      "description": "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`.",
      "mcp": null,
      "http": null
    },
    {
      "id": "apply_ops",
      "label": "Save the change as one edit",
      "description": "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": {
        "method": "POST",
        "path": "/v1/diagrams/${SCENE_ID}/revisions"
      }
    },
    {
      "id": "render",
      "label": "Render the revision",
      "description": "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": {
        "method": "GET",
        "path": "/v1/diagrams/${SCENE_ID}/render"
      }
    }
  ]
}