# Canvas: Diagram Mode Diagram-mode is the second of Gakaso's two project kinds (the other is application mode — see `/canvas/application-mode.md`). Where application mode is a tldraw-based canvas of UI shapes, diagram mode is a React Flow–based node/edge editor for flowcharts, architecture diagrams, org charts, and similar structured diagrams. ## When to use it Use diagram mode whenever the human's request is about *showing how something works* or *how a process flows* rather than about UI: "diagram the auth flow," "show me the system architecture," "map out the onboarding process," "draw the org chart." Application mode and diagram mode are separate project kinds — pick the one that matches the request before creating a project (or route to the right existing project if one already exists). At project creation, `kind` is `"application"` or `"diagram"`. When `kind="diagram"`, a `diagramKind` must also be supplied. Implemented diagram kinds: `flowchart`, `orgchart`, `network`, `er` (entity-relationship), `sequence`, `mindmap`, `generic-graph`. ## Nodes, clusters, and edges Diagram nodes (`gks-node`) support these visual kinds: `circle`, `rectangle`, `diamond`, `hexagon`, `actor`, `entity`, `process`, `decision`, `data`, `document`, `cloud`. Each node carries a label and optional tags. `gks-cluster` is a related primitive used to group nodes visually (e.g. a bounding box around a subsystem) — it's treated the same as a node by the layout engine. Diagram edges (`gks-edge`) support these relationship kinds: `association`, `inheritance`, `flow`, `composition`, `dependency`, `message` — each with a direction (`uni`/`bi`) and an optional strength 0–1 (rendered as stroke width). Softer/asynchronous relations (`dependency`, `message`) render dashed by default; the rest render solid. This node/edge vocabulary is intentionally generic enough to cover flowcharts, sequence-like diagrams, entity-relationship diagrams, and simple network/architecture diagrams with the same primitives — you do not need a different tool per diagram type, just a different combination of node/edge kinds. ### Creating nodes/edges: exact call shape Nodes and edges are created via `gakaso_add_component` (the same tool used for application-mode semantic shapes — see `/canvas/application-mode.md`), with `component.type` set to `"gks-node"`, `"gks-cluster"`, or `"gks-edge"`. Two things are easy to get wrong here: - `component.bounds` is a **nested** shape — `{ position: { x, y }, size: { width, height } }` — not flat `x`/`y`/`width`/`height`. (This differs from the faithful-import tools in `/mcp/faithful-roundtrip.md`, which *do* take flat `x`/`y`/`width`/`height` — the two tool families use different shapes for geometry, so don't copy-paste between them.) - For a `gks-edge`, the relationship data lives in `component.props`: `sourceId`, `targetId`, `direction` (`"uni"`/`"bi"`), `edgeKind` (one of the six relationship kinds above), and `strength` (0–1). An edge with a missing/invalid `sourceId`/`targetId` is still created but won't be usable by auto-layout (see below) or render meaningfully — always set both. ## Auto-layout Rather than hand-placing nodes (which tends to produce criss-crossing, hard-to-read diagrams), diagram mode includes a server-side auto-layout engine with four selectable strategies, run via `gakaso_diagram_auto_layout`: | Parameter | Default | Notes | |---|---|---| | `projectId` | — | Must be a project whose `kind` is `"diagram"` — calling this against an application-mode project fails with `INVALID_PARAMS` (`-32602`). | | `pageId` | `"default"` | Same default page id the in-browser diagram editor uses. | | `engine` | `"dagre"` | See table below. | | `direction` | `"TB"` | `TB` (top→bottom), `LR`, `BT`, `RL`. | | `nodeSpacing` | 60px | Override node-to-node spacing. | | `rankSpacing` | 120px | Override rank-to-rank spacing. | | Engine | Best for | |---|---| | `dagre` | Lightweight default; layered top-to-bottom or left-to-right DAGs | | `elk-layered` | Hierarchical / Sugiyama-style layered layout | | `elk-mrtree` | Multi-rooted tree layout; good for org charts and sitemaps | | `elk-force` | Force-directed layout; good for non-hierarchical network graphs | The call reads every `gks-node`/`gks-cluster` and `gks-edge` on the page, runs the chosen engine, and writes new `x`/`y` back onto each node/cluster in one pass — it fails with `NOT_FOUND` if there are no nodes on the page yet, so create your nodes/edges first. It's idempotent: re-running with the same inputs and no changes made in between skips writes for nodes whose position wouldn't actually change, and returns a `sample` of up to 3 updated `{id, x, y}` plus `updated` (a count) so you can sanity-check the result without re-fetching the whole canvas. Because the layout engine takes a plain `{id, width, height, source, target}` input shape, it runs identically whether invoked from the web client or from an MCP tool call — you get the same deterministic arrangement either way. ## Recommended workflow for building a diagram from a request 1. If the request is ambiguous ("show me how it works"), consult `gakaso://manuals/diagram-selection` and `gakaso://diagram-templates/index` first — see `/design/diagram-intelligence.md` — to pick the closest-matching template rather than improvising a structure. 2. Create (or select) a diagram-kind project/page with the matching `diagramKind` (`gakaso_create_project` with `kind: "diagram"`). 3. Create nodes and edges via `gakaso_add_component` (or `gakaso_batch_add_components` for many at once), using the node/edge kind vocabulary and call shape above. 4. Run `gakaso_diagram_auto_layout` rather than hand-placing coordinates. 5. Optionally take a snapshot (`gakaso_render_snapshot`) or run the visual/quality-check tooling described in `/design/diagram-intelligence.md` before handing the result back to the human. For the full MCP tool catalog (including canvas CRUD tools shared with application mode), see `/mcp/overview.md`.