DEV Community

Cover image for Let Claude Code draw your architecture diagram — and keep the box you moved
metataro
metataro

Posted on

Let Claude Code draw your architecture diagram — and keep the box you moved

#mcp #claudecode #diagrams #opensource

Asking an AI to draw an architecture diagram works fine — the first time.

The trouble starts with the second one. The architecture changes, you ask the AI to update the diagram, and the layout you spent ten minutes tidying is gone. So you stop asking. A month later the diagram is fiction.

zumen is an open-source diagram editor built around that second drawing.

The AI draws; a person moves one box; the AI is asked again and adds a node; the moved box stays put

The one idea: the AI may not write where you wrote

A zumen diagram is one YAML file. The AI writes nodes: and edges:. When you drag a box, the position goes into a separate pins: block — and the AI is not allowed to write pins:.

nodes:
  - id: api
    label: Order API
  - id: db
    label: Order DB
edges:
  - from: api
    to: db
pins:
  db:
    position: { x: 40, y: 170 }   # you put it here; regeneration cannot move it
Enter fullscreen mode Exit fullscreen mode

Regenerate as often as you like: the AI rewrites the nodes and edges, your pins stay. Across 10 real AI round trips, every human edit survived; a pin survives regeneration in all 389 bundled example drawings.

Set it up in Claude Code 

claude mcp add zumen -- npx -y @metataro/zumen-mcp
Enter fullscreen mode Exit fullscreen mode

Other MCP clients: run npx -y @metataro/zumen-mcp as a stdio server.

The agent gets:

  • zumen_spec — the format, read first
  • zumen_examples — 389 worked examples to learn the notation from
  • zumen_propose — a proposal, shown to you as a diff. There is no tool that writes the file directly; a person presses apply
  • zumen_inspect — checks for crossings, overlapping boxes, labels that did not fit, lines of different colours running on top of each other
  • zumen_export — SVG, PNG, Mermaid, draw.io

The desktop app showing an AI proposal as a diff, with Apply and Cancel

Show what changed, to people who will never read YAML

From a clone of the repository:

pnpm compare before.zumen.yaml after.zumen.yaml out.svg
Enter fullscreen mode Exit fullscreen mode

Before and after, side by side: new nodes marked, removed ones dotted, and the nodes a person placed marked on both sides — so a reviewer can see at a glance that the hand edits survived.

Not only boxes and arrows

The same small set of primitives draws things most diagram tools never attempt: stage lighting plots in USITT RP-2 notation, pallet loading patterns in isometric (checked against the Japanese Industrial Standards), floor plans with door swings, periodontal charts, transit maps with parallel lines that don't hide each other. All 389 examples are in the gallery.

What it is not

Not a Figma replacement, not a general drawing program, not a web app or real-time collaboration tool. Editing features exist only as far as a person needs them to approve what the AI changed.

Links

Top comments (0)