# yctimlin/mcp_excalidraw architecture

> Architecture diagram of the GitHub repository yctimlin/mcp_excalidraw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yctimlin/mcp_excalidraw
- Repository: https://github.com/yctimlin/mcp_excalidraw

## Overview

The product is a local Excalidraw workbench driven by coding agents through CLI, MCP, or HTTP. The main loop is to create or convert a diagram, inspect and refine the live canvas, then export or share it. The README documents broader capabilities than the sampled source; paths and links for those features are included only where the tree or excerpts support them.

Main entry points: [`src/cli/run.ts`](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/cli/run.ts) (CLI dispatcher), [`src/core/canvas-client.ts`](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/core/canvas-client.ts) (Canvas API client), [`src/core/mcp-dispatch.ts`](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/core/mcp-dispatch.ts) (Tool dispatcher), [`frontend/src/App.tsx`](https://github.com/yctimlin/mcp_excalidraw/blob/main/frontend/src/App.tsx) (Excalidraw UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Agent interfaces"]
  node_cli_entry["CLI dispatcher<br/>[run.ts]"]
  node_mcp_entry["MCP stdio entry<br/>[index.ts]"]
  node_rest_api["Canvas REST API<br/>[server.ts]"]
end

subgraph group_control["Command orchestration"]
  node_cli_elements["Element commands<br/>[elements.ts]"]
  node_cli_scene["Scene commands<br/>[scene.ts]"]
  node_cli_arrange["Arrange commands<br/>[arrange.ts]"]
  node_cli_snapshot["Snapshot commands<br/>[snapshot.ts]"]
  node_cli_server["Server commands<br/>[server.ts]"]
  node_mcp_server["MCP tool server<br/>[mcp-server.ts]"]
  node_mcp_dispatch["Tool dispatcher<br/>[mcp-dispatch.ts]"]
  node_canvas_state["Canvas startup<br/>[canvas-state.ts]"]
end

subgraph group_canvas["Live canvas"]
  node_canvas_client["Canvas API client<br/>[canvas-client.ts]"]
  node_canvas_server["Canvas server<br/>[server.ts]"]
  node_browser_ui["Excalidraw UI<br/>[App.tsx]"]
  node_elements_store[("Live element state<br/>[server.ts]")]
end

subgraph group_diagram["Diagram operations"]
  node_scene_restore["Scene normalization<br/>[scene.ts]"]
  node_geometry["Layout operations<br/>[geometry.ts]"]
  node_scene_io["Scene file I/O<br/>[scene-io.ts]"]
  node_share_url["Share export<br/>[share-url.ts]"]
  node_mermaid["Mermaid converter"]
end

node_agent(("Coding agent"))
node_cli_user(("CLI user"))
node_mcp_client(("MCP client"))
node_http_client(("HTTP client"))
node_excalidraw_com(("Excalidraw sharing"))

node_agent -->|"runs commands"| node_cli_entry
node_agent -->|"requests tools"| node_mcp_client
node_cli_user -->|"runs commands"| node_cli_entry
node_mcp_client -->|"stdio requests"| node_mcp_entry
node_http_client -->|"HTTP requests"| node_rest_api
node_cli_entry -->|"dispatches"| node_cli_elements
node_cli_entry -->|"dispatches"| node_cli_scene
node_cli_entry -->|"dispatches"| node_cli_arrange
node_cli_entry -->|"dispatches"| node_cli_snapshot
node_cli_entry -->|"dispatches"| node_cli_server
node_mcp_entry -->|"starts"| node_mcp_server
node_mcp_server -->|"dispatches tools"| node_mcp_dispatch
node_mcp_dispatch -->|"ensures ready"| node_canvas_state
node_cli_server -->|"starts or stops"| node_canvas_state
node_cli_elements -->|"reads and writes"| node_canvas_client
node_cli_scene -->|"imports and exports"| node_canvas_client
node_cli_arrange -->|"updates layout"| node_canvas_client
node_cli_snapshot -->|"uses canvas"| node_canvas_client
node_mcp_dispatch -->|"reads and writes"| node_canvas_client
node_mcp_dispatch -->|"arranges elements"| node_geometry
node_mcp_dispatch -->|"exports share URL"| node_share_url
node_canvas_client -->|"HTTP requests"| node_canvas_server
node_rest_api -->|"reads and writes"| node_elements_store
node_canvas_server -->|"serves UI"| node_browser_ui
node_browser_ui -->|"syncs over WebSocket"| node_canvas_server
node_browser_ui -->|"restores scenes"| node_scene_restore
node_browser_ui -->|"converts diagrams"| node_mermaid
node_browser_ui -->|"sends scene updates"| node_canvas_server
node_share_url -.->|"uploads encrypted scene"| node_excalidraw_com

click node_cli_entry "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/cli/run.ts"
click node_mcp_entry "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/index.ts"
click node_rest_api "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/server.ts"
click node_cli_elements "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/cli/commands/elements.ts"
click node_cli_scene "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/cli/commands/scene.ts"
click node_cli_arrange "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/cli/commands/arrange.ts"
click node_cli_snapshot "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/cli/commands/snapshot.ts"
click node_cli_server "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/cli/commands/server.ts"
click node_mcp_server "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/core/mcp-server.ts"
click node_mcp_dispatch "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/core/mcp-dispatch.ts"
click node_canvas_state "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/core/canvas-state.ts"
click node_canvas_client "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/core/canvas-client.ts"
click node_canvas_server "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/server.ts"
click node_browser_ui "https://github.com/yctimlin/mcp_excalidraw/blob/main/frontend/src/App.tsx"
click node_scene_restore "https://github.com/yctimlin/mcp_excalidraw/blob/main/frontend/src/utils/scene.ts"
click node_geometry "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/core/geometry.ts"
click node_scene_io "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/core/scene-io.ts"
click node_share_url "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/core/share-url.ts"
click node_mermaid "https://github.com/yctimlin/mcp_excalidraw/blob/main/frontend/src/utils/mermaidConverter.ts"
click node_elements_store "https://github.com/yctimlin/mcp_excalidraw/blob/main/src/server.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_entry,node_mcp_entry,node_rest_api,node_cli_user,node_mcp_client,node_http_client toneBlue
class node_cli_elements,node_cli_scene,node_cli_arrange,node_cli_snapshot,node_cli_server,node_mcp_server,node_mcp_dispatch,node_canvas_state toneAmber
class node_canvas_client,node_canvas_server,node_browser_ui,node_elements_store toneMint
class node_scene_restore,node_geometry,node_scene_io,node_share_url,node_mermaid toneRose
class node_agent,node_excalidraw_com toneIndigo
```

## Components

### Agent interfaces

- [CLI dispatcher](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/cli/run.ts): `src/cli/run.ts`
- [MCP stdio entry](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/index.ts): `src/index.ts`
- [Canvas REST API](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/server.ts): `src/server.ts`

### Command orchestration

- [Element commands](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/cli/commands/elements.ts): `src/cli/commands/elements.ts`
- [Scene commands](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/cli/commands/scene.ts): `src/cli/commands/scene.ts`
- [Arrange commands](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/cli/commands/arrange.ts): `src/cli/commands/arrange.ts`
- [Snapshot commands](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/cli/commands/snapshot.ts): `src/cli/commands/snapshot.ts`
- [Server commands](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/cli/commands/server.ts): `src/cli/commands/server.ts`
- [MCP tool server](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/core/mcp-server.ts): `src/core/mcp-server.ts`
- [Tool dispatcher](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/core/mcp-dispatch.ts): `src/core/mcp-dispatch.ts`
- [Canvas startup](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/core/canvas-state.ts): `src/core/canvas-state.ts`

### Live canvas

- [Canvas API client](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/core/canvas-client.ts): `src/core/canvas-client.ts`
- [Canvas server](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/server.ts): `src/server.ts`
- [Excalidraw UI](https://github.com/yctimlin/mcp_excalidraw/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Live element state](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/server.ts): `src/server.ts`

### Diagram operations

- [Scene normalization](https://github.com/yctimlin/mcp_excalidraw/blob/main/frontend/src/utils/scene.ts): `frontend/src/utils/scene.ts`
- [Layout operations](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/core/geometry.ts): `src/core/geometry.ts`
- [Scene file I/O](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/core/scene-io.ts): `src/core/scene-io.ts`
- [Share export](https://github.com/yctimlin/mcp_excalidraw/blob/main/src/core/share-url.ts): `src/core/share-url.ts`
- [Mermaid converter](https://github.com/yctimlin/mcp_excalidraw/blob/main/frontend/src/utils/mermaidConverter.ts): `frontend/src/utils/mermaidConverter.ts`

### Other components

- **Coding agent**
- **CLI user**
- **MCP client**
- **HTTP client**
- **Excalidraw sharing**

## Connections

- Coding agent → CLI dispatcher: runs commands
- Coding agent → MCP client: requests tools
- CLI user → CLI dispatcher: runs commands
- MCP client → MCP stdio entry: stdio requests
- HTTP client → Canvas REST API: HTTP requests
- CLI dispatcher → Element commands: dispatches
- CLI dispatcher → Scene commands: dispatches
- CLI dispatcher → Arrange commands: dispatches
- CLI dispatcher → Snapshot commands: dispatches
- CLI dispatcher → Server commands: dispatches
- MCP stdio entry → MCP tool server: starts
- MCP tool server → Tool dispatcher: dispatches tools
- Tool dispatcher → Canvas startup: ensures ready
- Server commands → Canvas startup: starts or stops
- Element commands → Canvas API client: reads and writes
- Scene commands → Canvas API client: imports and exports
- Arrange commands → Canvas API client: updates layout
- Snapshot commands → Canvas API client: uses canvas
- Tool dispatcher → Canvas API client: reads and writes
- Tool dispatcher → Layout operations: arranges elements
- Tool dispatcher → Share export: exports share URL
- Canvas API client → Canvas server: HTTP requests
- Canvas REST API → Live element state: reads and writes
- Canvas server → Excalidraw UI: serves UI
- Excalidraw UI → Canvas server: syncs over WebSocket
- Excalidraw UI → Scene normalization: restores scenes
- Excalidraw UI → Mermaid converter: converts diagrams
- Excalidraw UI → Canvas server: sends scene updates
- Share export → Excalidraw sharing: uploads encrypted scene