# backnotprop/plannotator architecture

> Architecture diagram of the GitHub repository backnotprop/plannotator, 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/backnotprop/plannotator
- Repository: https://github.com/backnotprop/plannotator

## Overview

Plannotator is a local browser-based review surface for AI coding agents. Users submit a plan, document, agent message, HTML artifact, or code change; an agent integration or CLI opens the relevant review surface, users annotate or review it, and feedback can be returned to the agent. Code review, AI-assisted review, guide sharing, and saved plan history are significant additional capabilities. The README documents the workflows; sampled excerpts are partial, so internal wiring beyond those documented flows is shown conservatively.

Main entry points: [`packages/editor/App.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/editor/App.tsx) (Document Editor), [`packages/review-editor/App.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/App.tsx) (Code Review UI), [`packages/server/index.ts`](https://github.com/backnotprop/plannotator/blob/main/packages/server/index.ts) (Review Server), [`packages/server/review.ts`](https://github.com/backnotprop/plannotator/blob/main/packages/server/review.ts) (Review API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integrations["Agent Integrations"]
  node_hooks["Agent Hooks<br/>[index.ts]"]
  node_opencode["OpenCode Plugin<br/>[index.ts]"]
  node_pi["Pi Extension<br/>[index.ts]"]
  node_droid["Droid Commands"]
  node_cli["CLI Entry<br/>[plannotator.js]"]
end

subgraph group_review["Review Surfaces"]
  node_editor["Document Editor<br/>[App.tsx]"]
  node_reviewui["Code Review UI<br/>[App.tsx]"]
  node_guideui["Guide Viewer<br/>[GuideViewer.tsx]"]
end

subgraph group_runtime["Local Runtime"]
  node_reviewserver["Review Server<br/>[index.ts]"]
  node_reviewroutes["Review API<br/>[review.ts]"]
  node_reviewstore["Review State<br/>[storage.ts]"]
end

subgraph group_domain["Review Logic"]
  node_annotate["Annotation Logic"]
  node_diff["Diff Processing<br/>[semantic-diff.ts]"]
  node_ai["AI Sessions<br/>[session-manager.ts]"]
  node_planstore[("Plan History<br/>[storage.ts]")]
end

subgraph group_services["Sharing Services"]
  node_guideshare["Guide Sharing<br/>[guide-share.ts]"]
  node_pastestore["Encrypted Paste<br/>[handler.ts]"]
end

node_user(("Developer"))
node_agent(("Coding Agent"))
node_vcs["Git / PR Providers"]
node_provider["AI Providers"]

node_agent -->|"submits plan"| node_hooks
node_agent -->|"invokes plugin"| node_opencode
node_agent -->|"invokes extension"| node_pi
node_agent -->|"invokes command"| node_droid
node_user -->|"runs command"| node_cli
node_hooks -->|"opens review"| node_editor
node_opencode -->|"opens review"| node_editor
node_pi -->|"opens review"| node_editor
node_droid -->|"opens review"| node_editor
node_cli -->|"starts session"| node_reviewserver
node_reviewserver -->|"serves editor"| node_editor
node_reviewserver -->|"serves review"| node_reviewui
node_user -->|"annotates document"| node_editor
node_user -->|"reviews changes"| node_reviewui
node_editor -->|"records annotations"| node_annotate
node_editor -->|"saves decisions"| node_planstore
node_editor -.->|"shares guide"| node_guideshare
node_guideshare -.->|"stores ciphertext"| node_pastestore
node_user -->|"starts code review"| node_reviewserver
node_reviewserver -->|"handles requests"| node_reviewroutes
node_reviewroutes -.->|"loads PR data"| node_vcs
node_reviewroutes -->|"processes changes"| node_diff
node_reviewroutes -->|"persists state"| node_reviewstore
node_reviewui -->|"requests review data"| node_reviewroutes
node_reviewui -.->|"requests AI review"| node_ai
node_editor -.->|"asks questions"| node_ai
node_ai -.->|"sends context"| node_provider
node_reviewui -->|"creates review comments"| node_annotate
node_reviewui -->|"returns feedback"| node_agent
node_editor -->|"returns feedback"| node_agent
node_user -.->|"views shared guide"| node_guideui

click node_hooks "https://github.com/backnotprop/plannotator/blob/main/apps/hook/server/index.ts"
click node_opencode "https://github.com/backnotprop/plannotator/blob/main/apps/opencode-plugin/index.ts"
click node_pi "https://github.com/backnotprop/plannotator/blob/main/apps/pi-extension/index.ts"
click node_droid "https://github.com/backnotprop/plannotator/blob/main/apps/droid-plugin/commands/plannotator-annotate.js"
click node_cli "https://github.com/backnotprop/plannotator/blob/main/bin/plannotator.js"
click node_editor "https://github.com/backnotprop/plannotator/blob/main/packages/editor/App.tsx"
click node_reviewui "https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/App.tsx"
click node_guideui "https://github.com/backnotprop/plannotator/blob/main/packages/guide-viewer/GuideViewer.tsx"
click node_reviewserver "https://github.com/backnotprop/plannotator/blob/main/packages/server/index.ts"
click node_reviewroutes "https://github.com/backnotprop/plannotator/blob/main/packages/server/review.ts"
click node_annotate "https://github.com/backnotprop/plannotator/blob/main/packages/core/annotation-threads.ts"
click node_diff "https://github.com/backnotprop/plannotator/blob/main/packages/shared/semantic-diff.ts"
click node_ai "https://github.com/backnotprop/plannotator/blob/main/packages/ai/session-manager.ts"
click node_planstore "https://github.com/backnotprop/plannotator/blob/main/packages/shared/storage.ts"
click node_reviewstore "https://github.com/backnotprop/plannotator/blob/main/packages/server/storage.ts"
click node_guideshare "https://github.com/backnotprop/plannotator/blob/main/packages/server/guide/guide-share.ts"
click node_pastestore "https://github.com/backnotprop/plannotator/blob/main/apps/paste-service/core/handler.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_hooks,node_opencode,node_pi,node_droid,node_cli toneBlue
class node_editor,node_reviewui,node_guideui toneAmber
class node_reviewserver,node_reviewroutes,node_reviewstore toneMint
class node_annotate,node_diff,node_ai,node_planstore toneRose
class node_guideshare,node_pastestore,node_user,node_agent,node_vcs,node_provider toneIndigo
```

## Components

### Agent Integrations

- [Agent Hooks](https://github.com/backnotprop/plannotator/blob/main/apps/hook/server/index.ts): `apps/hook/server/index.ts`
- [OpenCode Plugin](https://github.com/backnotprop/plannotator/blob/main/apps/opencode-plugin/index.ts): `apps/opencode-plugin/index.ts`
- [Pi Extension](https://github.com/backnotprop/plannotator/blob/main/apps/pi-extension/index.ts): `apps/pi-extension/index.ts`
- [Droid Commands](https://github.com/backnotprop/plannotator/blob/main/apps/droid-plugin/commands/plannotator-annotate.js): `apps/droid-plugin/commands/plannotator-annotate.js`
- [CLI Entry](https://github.com/backnotprop/plannotator/blob/main/bin/plannotator.js): `bin/plannotator.js`

### Review Surfaces

- [Document Editor](https://github.com/backnotprop/plannotator/blob/main/packages/editor/App.tsx): `packages/editor/App.tsx`
- [Code Review UI](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/App.tsx): `packages/review-editor/App.tsx`
- [Guide Viewer](https://github.com/backnotprop/plannotator/blob/main/packages/guide-viewer/GuideViewer.tsx): `packages/guide-viewer/GuideViewer.tsx`

### Local Runtime

- [Review Server](https://github.com/backnotprop/plannotator/blob/main/packages/server/index.ts): `packages/server/index.ts`
- [Review API](https://github.com/backnotprop/plannotator/blob/main/packages/server/review.ts): `packages/server/review.ts`
- [Review State](https://github.com/backnotprop/plannotator/blob/main/packages/server/storage.ts): `packages/server/storage.ts`

### Review Logic

- [Annotation Logic](https://github.com/backnotprop/plannotator/blob/main/packages/core/annotation-threads.ts): `packages/core/annotation-threads.ts`
- [Diff Processing](https://github.com/backnotprop/plannotator/blob/main/packages/shared/semantic-diff.ts): `packages/shared/semantic-diff.ts`
- [AI Sessions](https://github.com/backnotprop/plannotator/blob/main/packages/ai/session-manager.ts): `packages/ai/session-manager.ts`
- [Plan History](https://github.com/backnotprop/plannotator/blob/main/packages/shared/storage.ts): `packages/shared/storage.ts`

### Sharing Services

- [Guide Sharing](https://github.com/backnotprop/plannotator/blob/main/packages/server/guide/guide-share.ts): `packages/server/guide/guide-share.ts`
- [Encrypted Paste](https://github.com/backnotprop/plannotator/blob/main/apps/paste-service/core/handler.ts): `apps/paste-service/core/handler.ts`

### Other components

- **Developer**
- **Coding Agent**
- **Git / PR Providers**
- **AI Providers**

## Connections

- Coding Agent → Agent Hooks: submits plan
- Coding Agent → OpenCode Plugin: invokes plugin
- Coding Agent → Pi Extension: invokes extension
- Coding Agent → Droid Commands: invokes command
- Developer → CLI Entry: runs command
- Agent Hooks → Document Editor: opens review
- OpenCode Plugin → Document Editor: opens review
- Pi Extension → Document Editor: opens review
- Droid Commands → Document Editor: opens review
- CLI Entry → Review Server: starts session
- Review Server → Document Editor: serves editor
- Review Server → Code Review UI: serves review
- Developer → Document Editor: annotates document
- Developer → Code Review UI: reviews changes
- Document Editor → Annotation Logic: records annotations
- Document Editor → Plan History: saves decisions
- Document Editor → Guide Sharing: shares guide
- Guide Sharing → Encrypted Paste: stores ciphertext
- Developer → Review Server: starts code review
- Review Server → Review API: handles requests
- Review API → Git / PR Providers: loads PR data
- Review API → Diff Processing: processes changes
- Review API → Review State: persists state
- Code Review UI → Review API: requests review data
- Code Review UI → AI Sessions: requests AI review
- Document Editor → AI Sessions: asks questions
- AI Sessions → AI Providers: sends context
- Code Review UI → Annotation Logic: creates review comments
- Code Review UI → Coding Agent: returns feedback
- Document Editor → Coding Agent: returns feedback
- Developer → Guide Viewer: views shared guide