# petergyang/human-review architecture

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

- Interactive diagram: https://gitdiagram.com/petergyang/human-review
- Repository: https://github.com/petergyang/human-review

## Overview

Human Review is a local browser-based review tool for HTML, Markdown, and localhost pages. A user opens a target through the CLI; the local server presents it in a review interface where edits and comments are collected and sent as a batch for the AI agent to apply. The README documents a broad set of editing and commenting capabilities; sampled SDK and client code supports the editing, anchoring, undo, and handoff roles shown here. Unsampled routes and internal call details are omitted where wiring is uncertain.

Main entry points: [`src/server.js`](https://github.com/petergyang/human-review/blob/main/src/server.js) (Review server), [`src/chrome-client.js`](https://github.com/petergyang/human-review/blob/main/src/chrome-client.js) (Review interface), [`src/sdk.js`](https://github.com/petergyang/human-review/blob/main/src/sdk.js) (Artifact SDK), [`src/cli.js`](https://github.com/petergyang/human-review/blob/main/src/cli.js) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and Handoff"]
  node_cli["CLI commands<br/>[cli.js]"]
  node_skill["Agent instructions<br/>[SKILL.md]"]
  node_setup["Skill setup<br/>[setup.js]"]
end

subgraph group_session["Review Session"]
  node_server["Review server<br/>[server.js]"]
  node_chrome["Review interface<br/>[chrome-client.js]"]
  node_chromeui["Review shell<br/>[chrome.html]"]
  node_sessionlogic["Session helpers<br/>[chrome-session.js]"]
end

subgraph group_artifact["Artifact Editing"]
  node_sdk["Artifact SDK<br/>[sdk.js]"]
  node_editing["Edit operations<br/>[editing.js]"]
  node_anchors["Comment anchoring<br/>[anchor-text.js]"]
  node_serialize["Document serialization<br/>[serialize.js]"]
  node_policy["Frame security<br/>[frame-policy.js]"]
end

subgraph group_state["Persistence and Rendering"]
  node_store[("Review state<br/>[state.js]")]
  node_paths["Target identity<br/>[paths.js]"]
  node_transform["HTML bootstrap<br/>[html-transform.js]"]
  node_markdown["Markdown renderer<br/>[markdown.js]"]
end

node_user(("Reviewer"))
node_agent(("AI agent"))
node_localpage(("Localhost page"))

node_user -->|"opens target"| node_cli
node_cli -->|"starts or requests"| node_server
node_cli -->|"polls for batch"| node_agent
node_agent -.->|"requests skill setup"| node_setup
node_setup -->|"installs instructions"| node_skill
node_skill -->|"guides review"| node_agent
node_cli -->|"canonicalizes target"| node_paths
node_server -->|"reads and writes state"| node_store
node_server -->|"resolves target"| node_paths
node_server -->|"injects or strips SDK"| node_transform
node_server -->|"renders Markdown"| node_markdown
node_server -->|"serves review shell"| node_chromeui
node_server -->|"serves client"| node_chrome
node_server -.->|"loads localhost page"| node_localpage
node_user -->|"reviews and sends"| node_chrome
node_chrome -->|"requests pages and submits batch"| node_server
node_chrome -->|"uses page helpers"| node_sessionlogic
node_chrome -->|"sets iframe sandbox"| node_policy
node_chrome -->|"exchanges messages"| node_sdk
node_sdk -->|"applies edit decisions"| node_editing
node_sdk -->|"resolves comment quotes"| node_anchors
node_sdk -->|"serializes document"| node_serialize
node_sdk -->|"reports edits and comments"| node_chrome
node_server -->|"delivers feedback batch"| node_agent
node_markdown -.->|"loads diagrams"| node_agent

click node_cli "https://github.com/petergyang/human-review/blob/main/src/cli.js"
click node_skill "https://github.com/petergyang/human-review/blob/main/src/SKILL.md"
click node_setup "https://github.com/petergyang/human-review/blob/main/src/setup.js"
click node_server "https://github.com/petergyang/human-review/blob/main/src/server.js"
click node_chrome "https://github.com/petergyang/human-review/blob/main/src/chrome-client.js"
click node_chromeui "https://github.com/petergyang/human-review/blob/main/src/chrome.html"
click node_sessionlogic "https://github.com/petergyang/human-review/blob/main/src/chrome-session.js"
click node_sdk "https://github.com/petergyang/human-review/blob/main/src/sdk.js"
click node_editing "https://github.com/petergyang/human-review/blob/main/src/editing.js"
click node_anchors "https://github.com/petergyang/human-review/blob/main/src/anchor-text.js"
click node_serialize "https://github.com/petergyang/human-review/blob/main/src/serialize.js"
click node_policy "https://github.com/petergyang/human-review/blob/main/src/frame-policy.js"
click node_store "https://github.com/petergyang/human-review/blob/main/src/state.js"
click node_paths "https://github.com/petergyang/human-review/blob/main/src/paths.js"
click node_transform "https://github.com/petergyang/human-review/blob/main/src/html-transform.js"
click node_markdown "https://github.com/petergyang/human-review/blob/main/src/markdown.js"

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,node_skill,node_setup,node_user toneBlue
class node_server,node_chrome,node_chromeui,node_sessionlogic toneAmber
class node_sdk,node_editing,node_anchors,node_serialize,node_policy toneMint
class node_store,node_paths,node_transform,node_markdown toneRose
class node_agent,node_localpage toneIndigo
```

## Components

### Entry and Handoff

- [CLI commands](https://github.com/petergyang/human-review/blob/main/src/cli.js): `src/cli.js`
- [Agent instructions](https://github.com/petergyang/human-review/blob/main/src/SKILL.md): `src/SKILL.md`
- [Skill setup](https://github.com/petergyang/human-review/blob/main/src/setup.js): `src/setup.js`

### Review Session

- [Review server](https://github.com/petergyang/human-review/blob/main/src/server.js): `src/server.js`
- [Review interface](https://github.com/petergyang/human-review/blob/main/src/chrome-client.js): `src/chrome-client.js`
- [Review shell](https://github.com/petergyang/human-review/blob/main/src/chrome.html): `src/chrome.html`
- [Session helpers](https://github.com/petergyang/human-review/blob/main/src/chrome-session.js): `src/chrome-session.js`

### Artifact Editing

- [Artifact SDK](https://github.com/petergyang/human-review/blob/main/src/sdk.js): `src/sdk.js`
- [Edit operations](https://github.com/petergyang/human-review/blob/main/src/editing.js): `src/editing.js`
- [Comment anchoring](https://github.com/petergyang/human-review/blob/main/src/anchor-text.js): `src/anchor-text.js`
- [Document serialization](https://github.com/petergyang/human-review/blob/main/src/serialize.js): `src/serialize.js`
- [Frame security](https://github.com/petergyang/human-review/blob/main/src/frame-policy.js): `src/frame-policy.js`

### Persistence and Rendering

- [Review state](https://github.com/petergyang/human-review/blob/main/src/state.js): `src/state.js`
- [Target identity](https://github.com/petergyang/human-review/blob/main/src/paths.js): `src/paths.js`
- [HTML bootstrap](https://github.com/petergyang/human-review/blob/main/src/html-transform.js): `src/html-transform.js`
- [Markdown renderer](https://github.com/petergyang/human-review/blob/main/src/markdown.js): `src/markdown.js`

### Other components

- **Reviewer**
- **AI agent**
- **Localhost page**

## Connections

- Reviewer → CLI commands: opens target
- CLI commands → Review server: starts or requests
- CLI commands → AI agent: polls for batch
- AI agent → Skill setup: requests skill setup
- Skill setup → Agent instructions: installs instructions
- Agent instructions → AI agent: guides review
- CLI commands → Target identity: canonicalizes target
- Review server → Review state: reads and writes state
- Review server → Target identity: resolves target
- Review server → HTML bootstrap: injects or strips SDK
- Review server → Markdown renderer: renders Markdown
- Review server → Review shell: serves review shell
- Review server → Review interface: serves client
- Review server → Localhost page: loads localhost page
- Reviewer → Review interface: reviews and sends
- Review interface → Review server: requests pages and submits batch
- Review interface → Session helpers: uses page helpers
- Review interface → Frame security: sets iframe sandbox
- Review interface → Artifact SDK: exchanges messages
- Artifact SDK → Edit operations: applies edit decisions
- Artifact SDK → Comment anchoring: resolves comment quotes
- Artifact SDK → Document serialization: serializes document
- Artifact SDK → Review interface: reports edits and comments
- Review server → AI agent: delivers feedback batch
- Markdown renderer → AI agent: loads diagrams