# ruben-hayrapetyan/ccanvas architecture

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

- Interactive diagram: https://gitdiagram.com/ruben-hayrapetyan/ccanvas
- Repository: https://github.com/ruben-hayrapetyan/ccanvas
- Video tour (about a minute): https://gitdiagram.com/ruben-hayrapetyan/ccanvas/video

## Overview

ccanvas is a desktop/web infinite-canvas workspace for driving Claude Code alongside shells, files, editors, and live previews. The main workflow is to create or open a folder-bound canvas, add and arrange widgets, work in agents or terminals, and save the workspace. Supporting branches cover agent status and transcript-derived context, file and editor access, and workspace navigation and recall. The README documents several capabilities whose implementations were not sampled; those are represented at their documented paths, with uncertain internal wiring omitted.

Main entry points: [`src/store/workspace.ts`](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/store/workspace.ts) (Workspace store), [`src/lib/backend.ts`](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/backend.ts) (Backend client), [`src/canvas/Canvas.tsx`](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/canvas/Canvas.tsx) (Infinite canvas), [`src/lib/terminal.ts`](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/terminal.ts) (Terminal runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surface["Canvas surface"]
  node_app["App shell<br/>[App.tsx]"]
  node_canvas["Infinite canvas<br/>[Canvas.tsx]"]
  node_element["Canvas elements<br/>[ElementView.tsx]"]
end

subgraph group_workspace["Workspace state"]
  node_store["Workspace store<br/>[workspace.ts]"]
  node_persistence["Workspace persistence<br/>[persistence.ts]"]
end

subgraph group_agents["Agents and widgets"]
  node_terminal["Terminal runtime<br/>[terminal.ts]"]
  node_agent["Agent orchestration<br/>[agents.ts]"]
  node_transcript["Session transcripts<br/>[transcript.ts]"]
  node_context["Context meter<br/>[context.ts]"]
  node_sessiontitle["Session titles<br/>[sessionTitle.ts]"]
  node_widgetbodies["Widget views<br/>[TerminalBody.tsx]"]
  node_fileviews["File and editor views<br/>[FilesBody.tsx]"]
end

subgraph group_integrations["System integrations"]
  node_backendclient["Backend client<br/>[backend.ts]"]
  node_tauri["Desktop backend<br/>[lib.rs]"]
  node_pty["Native PTY<br/>[pty.rs]"]
  node_webbackend["Local web backend<br/>[pty-server.mjs]"]
  node_usage["Plan usage<br/>[plan_usage.rs]"]
end

subgraph group_navigation["Navigation and tools"]
  node_follow["Follow camera"]
  node_search["Canvas search<br/>[CanvasSearch.tsx]"]
  node_tracking["File tracking<br/>[tracker.ts]"]
  node_memory["Memory panel<br/>[MemoryPanel.tsx]"]
  node_checkpoints["Checkpoints<br/>[checkpoints.ts]"]
  node_prompts["Prompt library<br/>[PromptLibrary.tsx]"]
end

node_user(("Workspace user"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_canvas
node_canvas -->|"reads and updates"| node_store
node_canvas -->|"renders"| node_element
node_store -->|"loads and saves"| node_persistence
node_store -->|"opens and saves files"| node_backendclient
node_element -->|"renders widgets"| node_widgetbodies
node_widgetbodies -->|"starts sessions"| node_terminal
node_terminal -->|"connects for PTY"| node_backendclient
node_backendclient -.->|"invokes desktop commands"| node_tauri
node_tauri -->|"manages PTYs"| node_pty
node_backendclient -.->|"requests local services"| node_webbackend
node_agent -->|"manages agents"| node_terminal
node_context -->|"reads session data"| node_transcript
node_sessiontitle -->|"reads session data"| node_transcript
node_follow -->|"selects and centers agents"| node_store
node_follow -->|"observes status"| node_agent
node_search -->|"searches and focuses"| node_store
node_tracking -->|"tracks agent files"| node_store
node_memory -->|"reads folder memory"| node_backendclient
node_checkpoints -->|"uses Git and files"| node_backendclient
node_prompts -->|"manages prompts"| node_store
node_usage -.->|"provides plan usage"| node_backendclient

click node_app "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/App.tsx"
click node_canvas "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/canvas/Canvas.tsx"
click node_element "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/canvas/ElementView.tsx"
click node_store "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/store/workspace.ts"
click node_persistence "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/persistence.ts"
click node_terminal "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/terminal.ts"
click node_agent "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/agents.ts"
click node_transcript "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/transcript.ts"
click node_context "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/context.ts"
click node_sessiontitle "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/sessionTitle.ts"
click node_widgetbodies "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/widgets/TerminalBody.tsx"
click node_fileviews "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/widgets/FilesBody.tsx"
click node_backendclient "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/backend.ts"
click node_tauri "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src-tauri/src/lib.rs"
click node_pty "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src-tauri/src/pty.rs"
click node_webbackend "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/server/pty-server.mjs"
click node_follow "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/ui/FollowController.tsx"
click node_search "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/ui/CanvasSearch.tsx"
click node_tracking "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/tracker.ts"
click node_memory "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/ui/MemoryPanel.tsx"
click node_checkpoints "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/checkpoints.ts"
click node_prompts "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/ui/PromptLibrary.tsx"
click node_usage "https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src-tauri/src/plan_usage.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_app,node_canvas,node_element,node_user toneBlue
class node_store,node_persistence toneAmber
class node_terminal,node_agent,node_transcript,node_context,node_sessiontitle,node_widgetbodies,node_fileviews toneMint
class node_backendclient,node_tauri,node_pty,node_webbackend,node_usage toneRose
class node_follow,node_search,node_tracking,node_memory,node_checkpoints,node_prompts toneIndigo
```

## Components

### Canvas surface

- [App shell](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/App.tsx): `src/App.tsx`
- [Infinite canvas](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/canvas/Canvas.tsx): `src/canvas/Canvas.tsx`
- [Canvas elements](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/canvas/ElementView.tsx): `src/canvas/ElementView.tsx`

### Workspace state

- [Workspace store](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/store/workspace.ts): `src/store/workspace.ts`
- [Workspace persistence](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/persistence.ts): `src/lib/persistence.ts`

### Agents and widgets

- [Terminal runtime](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/terminal.ts): `src/lib/terminal.ts`
- [Agent orchestration](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/agents.ts): `src/lib/agents.ts`
- [Session transcripts](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/transcript.ts): `src/lib/transcript.ts`
- [Context meter](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/context.ts): `src/lib/context.ts`
- [Session titles](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/sessionTitle.ts): `src/lib/sessionTitle.ts`
- [Widget views](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/widgets/TerminalBody.tsx): `src/widgets/TerminalBody.tsx`
- [File and editor views](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/widgets/FilesBody.tsx): `src/widgets/FilesBody.tsx`

### System integrations

- [Backend client](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/backend.ts): `src/lib/backend.ts`
- [Desktop backend](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src-tauri/src/lib.rs): `src-tauri/src/lib.rs`
- [Native PTY](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src-tauri/src/pty.rs): `src-tauri/src/pty.rs`
- [Local web backend](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/server/pty-server.mjs): `server/pty-server.mjs`
- [Plan usage](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src-tauri/src/plan_usage.rs): `src-tauri/src/plan_usage.rs`

### Navigation and tools

- [Follow camera](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/ui/FollowController.tsx): `src/ui/FollowController.tsx`
- [Canvas search](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/ui/CanvasSearch.tsx): `src/ui/CanvasSearch.tsx`
- [File tracking](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/tracker.ts): `src/lib/tracker.ts`
- [Memory panel](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/ui/MemoryPanel.tsx): `src/ui/MemoryPanel.tsx`
- [Checkpoints](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/lib/checkpoints.ts): `src/lib/checkpoints.ts`
- [Prompt library](https://github.com/ruben-hayrapetyan/ccanvas/blob/rubens-version/src/ui/PromptLibrary.tsx): `src/ui/PromptLibrary.tsx`

### Other components

- **Workspace user**

## Connections

- Workspace user → App shell: uses
- App shell → Infinite canvas: renders
- Infinite canvas → Workspace store: reads and updates
- Infinite canvas → Canvas elements: renders
- Workspace store → Workspace persistence: loads and saves
- Workspace store → Backend client: opens and saves files
- Canvas elements → Widget views: renders widgets
- Widget views → Terminal runtime: starts sessions
- Terminal runtime → Backend client: connects for PTY
- Backend client → Desktop backend: invokes desktop commands
- Desktop backend → Native PTY: manages PTYs
- Backend client → Local web backend: requests local services
- Agent orchestration → Terminal runtime: manages agents
- Context meter → Session transcripts: reads session data
- Session titles → Session transcripts: reads session data
- Follow camera → Workspace store: selects and centers agents
- Follow camera → Agent orchestration: observes status
- Canvas search → Workspace store: searches and focuses
- File tracking → Workspace store: tracks agent files
- Memory panel → Backend client: reads folder memory
- Checkpoints → Backend client: uses Git and files
- Prompt library → Workspace store: manages prompts
- Plan usage → Backend client: provides plan usage
