# devdotfast/whiteboard architecture

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

- Interactive diagram: https://gitdiagram.com/devdotfast/whiteboard
- Repository: https://github.com/devdotfast/whiteboard

## Overview

Whiteboard is a desktop workspace for humans and coding agents to create and inspect software reviews. An agent connects through the review interface, contributes diagrams and trace context, and the desktop presents the result alongside code and semantic diffs. Users can follow visualizations to source, inspect agent decisions, and share reviews. The README documents major capabilities; the sampled files show selected UI, protocol, trace-storage, and diff components, so some subsystem links below are documented rather than verified in implementation.

Main entry points: [`packages/review/app/src/App.tsx`](https://github.com/devdotfast/whiteboard/blob/main/packages/review/app/src/App.tsx) (Review UI), [`packages/review/app/src/host/review-client.ts`](https://github.com/devdotfast/whiteboard/blob/main/packages/review/app/src/host/review-client.ts) (Review client), [`packages/review/src/review-api/agent-client.ts`](https://github.com/devdotfast/whiteboard/blob/main/packages/review/src/review-api/agent-client.ts) (Agent review API), [`apps/review-desktop/code-oss/src/vs/review/services/reviewDiffViewService.ts`](https://github.com/devdotfast/whiteboard/blob/main/apps/review-desktop/code-oss/src/vs/review/services/reviewDiffViewService.ts) (Semantic diff)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Review workflow"]
  node_review_client["Review client<br/>[review-client.ts]"]
  node_review_protocol["Review protocol"]
  node_agent_api["Agent review API<br/>[agent-client.ts]"]
  node_review_server["Review services"]
end

subgraph group_desktop["Desktop experience"]
  node_review_app["Review UI<br/>[App.tsx]"]
  node_review_session["Review session<br/>[review-session.tsx]"]
  node_code_editor["Code editor"]
end

subgraph group_analysis["Code analysis"]
  node_semantic_diff["Semantic diff"]
  node_diff_view["Diff viewer<br/>[App.tsx]"]
  node_local_vcs["Local VCS<br/>[vcs.ts]"]
end

subgraph group_traces["Agent traces"]
  node_trace_core["Trace handling"]
  node_trace_store["Trace storage client<br/>[store-client.ts]"]
  node_trace_protocol["Trace store API<br/>[store-api.ts]"]
end

subgraph group_sharing["Review sharing"]
  node_share_client["Share client<br/>[client.ts]"]
  node_share_routes["Share routes<br/>[routes.ts]"]
  node_shared_review(("Shared review"))
end

node_human(("Human reviewer"))
node_agent(("Coding agent"))

node_human -->|"requests review"| node_agent
node_agent -->|"opens result"| node_review_app
node_agent -.->|"submits review"| node_agent_api
node_review_app -->|"uses session"| node_review_session
node_review_app -->|"uses client"| node_review_client
node_review_client -->|"calls protocol"| node_review_protocol
node_agent_api -.->|"serves requests"| node_review_server
node_review_app -->|"renders diff"| node_diff_view
node_diff_view -->|"shows changes"| node_semantic_diff
node_semantic_diff -.->|"compares revisions"| node_local_vcs
node_human -->|"navigates source"| node_code_editor
node_agent -->|"records decisions"| node_trace_core
node_trace_core -.->|"stores traces"| node_trace_store
node_trace_store -->|"uses store API"| node_trace_protocol
node_review_app -.->|"shares review"| node_share_client
node_share_client -.->|"uses routes"| node_share_routes
node_share_routes -.->|"publishes review"| node_shared_review
node_shared_review -->|"opens review"| node_human

click node_review_app "https://github.com/devdotfast/whiteboard/blob/main/packages/review/app/src/App.tsx"
click node_review_session "https://github.com/devdotfast/whiteboard/blob/main/packages/review/app/src/host/review-session.tsx"
click node_review_client "https://github.com/devdotfast/whiteboard/blob/main/packages/review/app/src/host/review-client.ts"
click node_review_protocol "https://github.com/devdotfast/whiteboard/blob/main/packages/review-protocol/src/review-api-client.ts"
click node_agent_api "https://github.com/devdotfast/whiteboard/blob/main/packages/review/src/review-api/agent-client.ts"
click node_review_server "https://github.com/devdotfast/whiteboard/tree/main/packages/review/src/server"
click node_semantic_diff "https://github.com/devdotfast/whiteboard/blob/main/apps/review-desktop/code-oss/src/vs/review/services/reviewDiffViewService.ts"
click node_diff_view "https://github.com/devdotfast/whiteboard/blob/main/packages/review/app/src/App.tsx"
click node_code_editor "https://github.com/devdotfast/whiteboard/blob/main/apps/review-desktop/code-oss/src/vs/review/browser/reviewPaneCompositePartService.ts"
click node_trace_core "https://github.com/devdotfast/whiteboard/blob/main/packages/trace-core/src/review-agent-traces.ts"
click node_trace_store "https://github.com/devdotfast/whiteboard/blob/main/packages/trace-core/src/store-client.ts"
click node_trace_protocol "https://github.com/devdotfast/whiteboard/blob/main/packages/trace-protocol/src/store-api.ts"
click node_local_vcs "https://github.com/devdotfast/whiteboard/blob/main/packages/local-vcs/src/vcs.ts"
click node_share_client "https://github.com/devdotfast/whiteboard/blob/main/packages/review/src/sharing/client.ts"
click node_share_routes "https://github.com/devdotfast/whiteboard/blob/main/packages/review/src/sharing/routes.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_review_client,node_review_protocol,node_agent_api,node_review_server,node_human toneBlue
class node_review_app,node_review_session,node_code_editor toneAmber
class node_semantic_diff,node_diff_view,node_local_vcs toneMint
class node_trace_core,node_trace_store,node_trace_protocol toneRose
class node_share_client,node_share_routes,node_shared_review,node_agent toneIndigo
```

## Components

### Review workflow

- [Review client](https://github.com/devdotfast/whiteboard/blob/main/packages/review/app/src/host/review-client.ts): `packages/review/app/src/host/review-client.ts`
- [Review protocol](https://github.com/devdotfast/whiteboard/blob/main/packages/review-protocol/src/review-api-client.ts): `packages/review-protocol/src/review-api-client.ts`
- [Agent review API](https://github.com/devdotfast/whiteboard/blob/main/packages/review/src/review-api/agent-client.ts): `packages/review/src/review-api/agent-client.ts`
- [Review services](https://github.com/devdotfast/whiteboard/tree/main/packages/review/src/server): `packages/review/src/server`

### Desktop experience

- [Review UI](https://github.com/devdotfast/whiteboard/blob/main/packages/review/app/src/App.tsx): `packages/review/app/src/App.tsx`
- [Review session](https://github.com/devdotfast/whiteboard/blob/main/packages/review/app/src/host/review-session.tsx): `packages/review/app/src/host/review-session.tsx`
- [Code editor](https://github.com/devdotfast/whiteboard/blob/main/apps/review-desktop/code-oss/src/vs/review/browser/reviewPaneCompositePartService.ts): `apps/review-desktop/code-oss/src/vs/review/browser/reviewPaneCompositePartService.ts`

### Code analysis

- [Semantic diff](https://github.com/devdotfast/whiteboard/blob/main/apps/review-desktop/code-oss/src/vs/review/services/reviewDiffViewService.ts): `apps/review-desktop/code-oss/src/vs/review/services/reviewDiffViewService.ts`
- [Diff viewer](https://github.com/devdotfast/whiteboard/blob/main/packages/review/app/src/App.tsx): `packages/review/app/src/App.tsx`
- [Local VCS](https://github.com/devdotfast/whiteboard/blob/main/packages/local-vcs/src/vcs.ts): `packages/local-vcs/src/vcs.ts`

### Agent traces

- [Trace handling](https://github.com/devdotfast/whiteboard/blob/main/packages/trace-core/src/review-agent-traces.ts): `packages/trace-core/src/review-agent-traces.ts`
- [Trace storage client](https://github.com/devdotfast/whiteboard/blob/main/packages/trace-core/src/store-client.ts): `packages/trace-core/src/store-client.ts`
- [Trace store API](https://github.com/devdotfast/whiteboard/blob/main/packages/trace-protocol/src/store-api.ts): `packages/trace-protocol/src/store-api.ts`

### Review sharing

- [Share client](https://github.com/devdotfast/whiteboard/blob/main/packages/review/src/sharing/client.ts): `packages/review/src/sharing/client.ts`
- [Share routes](https://github.com/devdotfast/whiteboard/blob/main/packages/review/src/sharing/routes.ts): `packages/review/src/sharing/routes.ts`
- **Shared review**

### Other components

- **Human reviewer**
- **Coding agent**

## Connections

- Human reviewer → Coding agent: requests review
- Coding agent → Review UI: opens result
- Coding agent → Agent review API: submits review
- Review UI → Review session: uses session (evidence: `packages/review/app/src/App.tsx`)
- Review UI → Review client: uses client (evidence: `packages/review/app/src/App.tsx`)
- Review client → Review protocol: calls protocol (evidence: `packages/review/app/src/host/review-client.ts`)
- Agent review API → Review services: serves requests
- Review UI → Diff viewer: renders diff (evidence: `packages/review/app/src/App.tsx`)
- Diff viewer → Semantic diff: shows changes
- Semantic diff → Local VCS: compares revisions
- Human reviewer → Code editor: navigates source
- Coding agent → Trace handling: records decisions
- Trace handling → Trace storage client: stores traces
- Trace storage client → Trace store API: uses store API (evidence: `packages/trace-core/src/store-client.ts`)
- Review UI → Share client: shares review
- Share client → Share routes: uses routes
- Share routes → Shared review: publishes review
- Shared review → Human reviewer: opens review