# zseven-w/openpencil architecture

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

- Interactive diagram: https://gitdiagram.com/zseven-w/openpencil
- Repository: https://github.com/zseven-w/openpencil

## Overview

OpenPencil is an AI-native vector design editor centered on creating and modifying `.op` canvas documents. The principal workflow is a user prompt or selection-driven request, routed through chat-agent orchestration to a model, then applied to the editor and rendered on the canvas. Major documented branches include multi-agent work, style guides, code export, CLI/MCP access, design-system kits, and real-time collaboration. Paths for several documented subsystems are only supported at crate-directory level; the excerpts do not establish every runtime call between them.

Main entry points: [`crates/op-chat-agent/src/chat_agent_loop.rs`](https://github.com/zseven-w/openpencil/blob/main/crates/op-chat-agent/src/chat_agent_loop.rs) (Agent orchestration), [`crates/op-editor-core/src`](https://github.com/zseven-w/openpencil/tree/main/crates/op-editor-core/src) (Editor state), [`crates/op-editor-core/src/chat.rs`](https://github.com/zseven-w/openpencil/blob/main/crates/op-editor-core/src/chat.rs) (Chat interface), [`crates/op-collab-host/src/runtime.rs`](https://github.com/zseven-w/openpencil/blob/main/crates/op-collab-host/src/runtime.rs) (Session host)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_creation["AI creation"]
  node_agent["Agent orchestration<br/>[chat_agent_loop.rs]"]
  node_agent_tools["Canvas tools"]
  node_design_agent["Agent teams"]
end

subgraph group_editor["Canvas editor"]
  node_chat["Chat interface<br/>[chat.rs]"]
  node_engine["Editor engine<br/>[op_engine.h]"]
  node_editor_core["Editor state"]
  node_document["OP document<br/>[snapshot.rs]"]
end

subgraph group_design["Design resources"]
  node_skills["Style guides"]
  node_design_systems["Design systems<br/>[design_systems.rs]"]
end

subgraph group_integration["Export and access"]
  node_codegen["Code generation<br/>[pipeline.rs]"]
  node_export["Platform export<br/>[codegen_targets.rs]"]
  node_cli["CLI and MCP"]
end

subgraph group_collaboration["Live collaboration"]
  node_collab_ui["Collaboration controls<br/>[collab_routes.rs]"]
  node_collab_host["Session host<br/>[runtime.rs]"]
  node_collab_protocol["Sync protocol<br/>[protocol.rs]"]
  node_relay["Relay service<br/>[server.rs]"]
end

node_user(("Designer"))
node_model{{"Model provider"}}
node_mcp_agent(("External agent"))
node_peer(("Collaborator"))

node_user -->|"prompts or selects"| node_chat
node_chat -->|"starts requests"| node_agent
node_agent -->|"streams requests"| node_model
node_model -->|"returns tokens"| node_agent
node_agent -->|"invokes tools"| node_agent_tools
node_agent_tools -->|"modifies canvas"| node_engine
node_engine -->|"updates state"| node_editor_core
node_editor_core -->|"serializes document"| node_document
node_agent -.->|"decomposes tasks"| node_design_agent
node_design_agent -.->|"dispatches subtasks"| node_model
node_chat -.->|"applies styles"| node_skills
node_editor_core -.->|"uses kits"| node_design_systems
node_user -->|"runs commands"| node_cli
node_mcp_agent -.->|"requests design tools"| node_cli
node_cli -.->|"controls editor"| node_editor_core
node_user -->|"requests export"| node_codegen
node_codegen -->|"produces code"| node_export
node_user -->|"starts or joins"| node_collab_ui
node_collab_ui -->|"controls session"| node_collab_host
node_collab_host -->|"synchronizes edits"| node_collab_protocol
node_collab_host -.->|"connects through"| node_relay
node_peer -.->|"joins session"| node_relay

click node_chat "https://github.com/zseven-w/openpencil/blob/main/crates/op-editor-core/src/chat.rs"
click node_agent "https://github.com/zseven-w/openpencil/blob/main/crates/op-chat-agent/src/chat_agent_loop.rs"
click node_agent_tools "https://github.com/zseven-w/openpencil/blob/main/crates/op-chat-agent/src/chat_canvas_tools.rs"
click node_design_agent "https://github.com/zseven-w/openpencil/blob/main/crates/op-chat-agent/src/design_agent_tools.rs"
click node_engine "https://github.com/zseven-w/openpencil/blob/main/crates/op-engine-ffi/include/op_engine.h"
click node_editor_core "https://github.com/zseven-w/openpencil/tree/main/crates/op-editor-core/src"
click node_document "https://github.com/zseven-w/openpencil/blob/main/crates/op-collab/src/snapshot.rs"
click node_skills "https://github.com/zseven-w/openpencil/tree/main/crates/op-ai-skills/src/style_guide"
click node_design_systems "https://github.com/zseven-w/openpencil/blob/main/crates/op-ai-skills/src/design_systems.rs"
click node_codegen "https://github.com/zseven-w/openpencil/blob/main/crates/op-codegen/src/ai/pipeline.rs"
click node_export "https://github.com/zseven-w/openpencil/blob/main/crates/op-codegen/src/codegen_targets.rs"
click node_cli "https://github.com/zseven-w/openpencil/tree/main/crates/op-cli/src"
click node_collab_ui "https://github.com/zseven-w/openpencil/blob/main/crates/op-editor-core/src/collab_routes.rs"
click node_collab_host "https://github.com/zseven-w/openpencil/blob/main/crates/op-collab-host/src/runtime.rs"
click node_collab_protocol "https://github.com/zseven-w/openpencil/blob/main/crates/op-collab/src/protocol.rs"
click node_relay "https://github.com/zseven-w/openpencil/blob/main/crates/op-collab-relay-server/src/server.rs"

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_agent,node_agent_tools,node_design_agent toneBlue
class node_chat,node_engine,node_editor_core,node_document toneAmber
class node_skills,node_design_systems toneMint
class node_codegen,node_export,node_cli toneRose
class node_collab_ui,node_collab_host,node_collab_protocol,node_relay,node_user,node_model,node_mcp_agent,node_peer toneIndigo
```

## Components

### AI creation

- [Agent orchestration](https://github.com/zseven-w/openpencil/blob/main/crates/op-chat-agent/src/chat_agent_loop.rs): `crates/op-chat-agent/src/chat_agent_loop.rs`
- [Canvas tools](https://github.com/zseven-w/openpencil/blob/main/crates/op-chat-agent/src/chat_canvas_tools.rs): `crates/op-chat-agent/src/chat_canvas_tools.rs`
- [Agent teams](https://github.com/zseven-w/openpencil/blob/main/crates/op-chat-agent/src/design_agent_tools.rs): `crates/op-chat-agent/src/design_agent_tools.rs`

### Canvas editor

- [Chat interface](https://github.com/zseven-w/openpencil/blob/main/crates/op-editor-core/src/chat.rs): `crates/op-editor-core/src/chat.rs`
- [Editor engine](https://github.com/zseven-w/openpencil/blob/main/crates/op-engine-ffi/include/op_engine.h): `crates/op-engine-ffi/include/op_engine.h`
- [Editor state](https://github.com/zseven-w/openpencil/tree/main/crates/op-editor-core/src): `crates/op-editor-core/src`
- [OP document](https://github.com/zseven-w/openpencil/blob/main/crates/op-collab/src/snapshot.rs): `crates/op-collab/src/snapshot.rs`

### Design resources

- [Style guides](https://github.com/zseven-w/openpencil/tree/main/crates/op-ai-skills/src/style_guide): `crates/op-ai-skills/src/style_guide`
- [Design systems](https://github.com/zseven-w/openpencil/blob/main/crates/op-ai-skills/src/design_systems.rs): `crates/op-ai-skills/src/design_systems.rs`

### Export and access

- [Code generation](https://github.com/zseven-w/openpencil/blob/main/crates/op-codegen/src/ai/pipeline.rs): `crates/op-codegen/src/ai/pipeline.rs`
- [Platform export](https://github.com/zseven-w/openpencil/blob/main/crates/op-codegen/src/codegen_targets.rs): `crates/op-codegen/src/codegen_targets.rs`
- [CLI and MCP](https://github.com/zseven-w/openpencil/tree/main/crates/op-cli/src): `crates/op-cli/src`

### Live collaboration

- [Collaboration controls](https://github.com/zseven-w/openpencil/blob/main/crates/op-editor-core/src/collab_routes.rs): `crates/op-editor-core/src/collab_routes.rs`
- [Session host](https://github.com/zseven-w/openpencil/blob/main/crates/op-collab-host/src/runtime.rs): `crates/op-collab-host/src/runtime.rs`
- [Sync protocol](https://github.com/zseven-w/openpencil/blob/main/crates/op-collab/src/protocol.rs): `crates/op-collab/src/protocol.rs`
- [Relay service](https://github.com/zseven-w/openpencil/blob/main/crates/op-collab-relay-server/src/server.rs): `crates/op-collab-relay-server/src/server.rs`

### Other components

- **Designer**
- **Model provider**
- **External agent**
- **Collaborator**

## Connections

- Designer → Chat interface: prompts or selects
- Chat interface → Agent orchestration: starts requests
- Agent orchestration → Model provider: streams requests
- Model provider → Agent orchestration: returns tokens
- Agent orchestration → Canvas tools: invokes tools
- Canvas tools → Editor engine: modifies canvas
- Editor engine → Editor state: updates state
- Editor state → OP document: serializes document
- Agent orchestration → Agent teams: decomposes tasks
- Agent teams → Model provider: dispatches subtasks
- Chat interface → Style guides: applies styles
- Editor state → Design systems: uses kits
- Designer → CLI and MCP: runs commands
- External agent → CLI and MCP: requests design tools
- CLI and MCP → Editor state: controls editor
- Designer → Code generation: requests export
- Code generation → Platform export: produces code
- Designer → Collaboration controls: starts or joins
- Collaboration controls → Session host: controls session
- Session host → Sync protocol: synchronizes edits
- Session host → Relay service: connects through
- Collaborator → Relay service: joins session