bv-venky / excalidraw-architect

Excalidraw Architect

The MCP server renders. This skill decides what to render and how much.

Picking the wrong diagram type is the most common way a diagram fails. A
cross-functional process drawn as a flowchart loses the handoffs that were the
entire point. A ranking drawn as a bar chart loses the ranking.

1. Before you draw

Ask: *would the reader learn more from this than from a well-written
paragraph or a three-column table?* If no, write the paragraph.

Don't draw for:

• A list of things → bullets or a table.
• A simple before/after → a two-column table.
• One shape → just write the sentence.

2. The two rules that carry most of the quality

Density target: ~4/10. Enough to be complete, not so dense it needs its
own legend. Above nine nodes it is usually two diagrams — draw an overview
and a detail. Two nodes that always travel together are one node.

Accent is reserved. Every spec accepts "focal": true on its elements.
Mark one or two — the thing you want looked at first. Marking five spends
the signal and leaves the reader with no entry point. Most elements should be
unmarked; that is what makes the marked one work.

A third, quieter rule: every connection should carry information. If the
relationship is already obvious from the layout, delete the line.

3. Picking a type

<!-- BEGIN:selection-table -->
| If you're showing… | Use | Not when |
|---|---|---|
| Components and the connections between them | architecture | (graph type — pass nodes + connections) |
| Decision logic with branches | flowchart | (graph type — pass nodes + connections) |
| Parent -> children: taxonomies, file hierarchies, decision breakdowns. | tree | Use org_chart for people or teams; use nested when containment is the point. |
| Human, team, or agent ownership: reporting lines, escalation, routing. | org_chart | Not for system components -- that is architecture. |
| States, transitions, and guards. Order lifecycles, retry machines, approval flows. | state | Not for time-ordered messages between actors -- that is sequence. |
| Hierarchy by containment or scope: bounded contexts, module trees, org scopes. | nested | Beyond three levels of nesting, split into an overview plus a detail diagram. |
| Stacked abstraction levels where each layer sits on the one below. | layers | If the layers exchange traffic in both directions, use architecture instead. |
| Multi-tier data storage with quality levels: bronze/silver/gold, raw/curated/serving. | medallion | Use data_flow when the emphasis is who does what rather than where data rests. |
| Entities, their fields, and relationships. Data models and schema documentation. | er | Above ~8 entities, split by bounded context. |
| End-to-end stack drawn inside one named boundary (a cluster, an account, a VPC). | high_level | Use architecture when the boundary is not the point. |
| Legacy landscape grouped by phase or department; the 'before' state. | it_state | Use architecture for a target-state design. |
| Cross-functional process where step ownership matters. Handoffs are the story. | swimlane | If every step has the same owner, use flowchart. |
| Multi-actor sequential workflow drawn as vertical actor columns with data handoffs. | process | Use swimlane for horizontal lanes and a wider flow. |
| A pipeline where each stage is tagged with the role that owns it. | data_flow | Use medallion when storage tiers, not roles, are the subject. |
| Integration topology of a platform: sources -> core -> consumers. | dp_integration | Use architecture when the core needs to be decomposed in detail. |
| Time-ordered messages between actors: API traces, protocols, incident replays. | sequence | Never draw a message arrow that points backwards in time; use state for lifecycles. |
| Events positioned in time along a single axis. Roadmaps, incident chronologies. | timeline | Use gantt when items have duration rather than a single instant. |
| Two-axis positioning and prioritization. Add quadrant_labels for a consultant 2x2. | quadrant | Use scatter when the axes carry real units rather than relative position. |
| Ranked hierarchy (mode='pyramid') or conversion drop-off (mode='funnel'). | pyramid | Use bar when the values matter more than the ranking. |
| Overlap between two or three sets, where the intersection is the insight. | venn | Four or more sets is unreadable -- use a table. |
| A reinforcing cycle; add a hub for shared state the stations write back to. | loop | Use process when the flow has a real beginning and end. |
| Tasks and phases with duration on a timeline. Shows overlap and parallel tracks. | gantt | Above ~12 tasks, collapse to a phase-level view. |
| Quantitative comparison across categories. Multiple series render as grouped bars. | bar | Use line when the x axis is continuous time. |
| Continuous trends over an ordered axis. Capped at 15 points per series. | line | Use bar for a handful of discrete categories. |
| Distribution and correlation between two continuous variables. | scatter | Use quadrant when position is relative judgement rather than measurement. |
<!-- END:selection-table -->

Rules of thumb:

• If a three-column table says the same thing, use the table.
• Combining two types? Pick the dominant axis. Don't hybridize grammars.
• Past the density budget? Split into overview + detail.

4. Calling the tools

list_diagram_types()            # the table above, from the server
get_diagram_schema("sequence")  # exact spec shape for one type
create_diagram(output_path="./x.excalidraw", diagram_type="sequence", spec={...})

architecture and flowchart are graph types and take nodes +
connections instead of a spec. Everything else takes diagram_type +
spec.

Every spec accepts optional title and subtitle.

Editing. Call get_diagram_info(path) to read the stored spec, then:

modify_diagram(path, [{"op": "update_spec", "patch": {"title": "New title"}}])

The patch is deep-merged. Lists are replaced wholesale — to change one
tier, send the whole tiers list.

Exporting. export_diagram(path, "./x.svg") for SVG; PNG needs the
optional cairosvg extra.

See [`references/types.md`](references/types.md) for the full spec shape and a
worked example of every type.

5. Anti-patterns

6. What the renderer already handles

Don't work around these — they are done for you:

• Layout. Never pass coordinates. The engine places and routes everything.

• Chrome vs content. Axes, gridlines, and lane dividers render crisp;
  shapes and data marks render hand-drawn. That contrast is deliberate.

• Themes. default, dark, colorful. Accent and series ramps adapt.
• Bindings. Arrows stay attached when a node is dragged in Excalidraw.