Design · Open Code Review (OCR)

High-Level Design (HLD)

↩ architecture.html · generated 2026-08-14

High-Level Design (HLD)

Companion diagram: diagrams/01_architecture.svg. Interactive version: architecture.html — click any module box in §7 there for a full paragraph per module: what actually happens, exactly how (or whether) a model is called, and which parts are deterministic vs. AI-driven.

Open Code Review (OCR) is a command-line application. You run one command (ocr) with a subcommand (review, scan, delegate, ...) and it looks at your local git repository. Internally, think of it as an editorial desk: an intake clerk (the CLI) decides which files are even in scope and what the house style is for each one, a desk editor (review/scan agent) hands one file at a time to a staff writer (the LLM tool-use loop), who can call out to a research assistant (the tool registry — read a file, search the codebase) before filing a comment, and every comment that comes back is fact-checked against the real diff before it's accepted. In delegation mode, the desk editor instead hands the assignment straight to a writer you already employ elsewhere (your own coding agent) and never talks to a model itself.

flowchart TB IN["Inputs
git repo · config.json · rule.json"] --> CLI["CLI (cmd/opencodereview)"] CLI --> DIFF["internal/diff
git diff / hunk parse / relocation"] CLI --> RULES["internal/config
rules · allowlist · templates"] DIFF --> AGENT["internal/agent (review)
internal/scan (full-file)"] RULES --> AGENT CLI --> DELEGATE["internal/delegate
no LLM call"] AGENT --> LOOP["internal/llmloop.Runner
shared tool-use loop"] LOOP <--> TOOLS["internal/tool + internal/mcp
file_read · search · code_comment"] LOOP <--> LLM["internal/llm
protocol resolve · retry"] LLM <--> PROVIDER(["LLM Provider API"]) LOOP --> SESSION["internal/session
history · manifest · resume"] SESSION --> OUT["Comments · SARIF · session JSONL"] SESSION --> VIEWER["internal/viewer
local web browser"] DELEGATE -. "via user's own agent" .-> OUT

1. Components and responsibilities

# Component Package Responsibility
1 CLI cmd/opencodereview Cobra command tree (review, scan, delegate, session, config, llm, rules, viewer, completion); resolves the LLM endpoint, loads config/rules, builds and dispatches to the right agent.
2 Diff engine internal/diff Git diff retrieval (workspace/range/commit), unified-diff parsing, .gitignore filtering, comment line-number resolution/relocation.
3 Config & rules internal/config/{rules,allowlist,template,toolsconfig} Path-based rule resolution, file-type allowlist, prompt templates (task_template.json, scan_template.json), tool enable/disable config.
4 Review agent internal/agent Orchestrates ocr review: load diffs → filter → dispatch per file → finalize the coverage manifest.
5 Scan agent internal/scan Orchestrates ocr scan: enumerate whole files → same dispatch pattern → optional dedup + project-summary passes.
6 Delegate internal/delegate Deterministic file selection + rule-group export for ocr delegate — makes no LLM call.
7 LLM loop internal/llmloop The shared tool-use conversation loop (Runner.RunPerFile) both agent and scan dispatch into; memory compression; token accounting.
8 Tools internal/tool The fixed toolset: file_read, file_find, file_read_diff, code_search, code_comment, task_done, plus the registry that also holds MCP tools.
9 MCP client internal/mcp Adapts external MCP-server tools into the same tool registry the built-ins use.
10 LLM transport internal/llm Resolves provider/protocol/model (env → config → preset); speaks Anthropic / OpenAI Chat Completions / OpenAI Responses; retries with backoff.
11 Session internal/session Per-run JSONL history + the immutable coverage manifest that powers --resume.
12 Viewer internal/viewer Local-only web server rendering a session's history as browsable HTML.
13 Telemetry internal/telemetry Opt-in OpenTelemetry spans/metrics — never load-bearing for a review's result.

2. Technology stack

3. Run / distribution model

OCR ships as a single static binary, installable via npm install -g @alibaba-group/open-code-review, an install script, or a GitHub Release download — plus integrations that don't require installing the binary at all: a GitHub Action (action.yml), CI examples for GitLab/Bitbucket/Gerrit/CodeUp/GitFlic (examples/), a VS Code extension (extensions/vscode/), and coding-agent plugins for Claude Code, Codex, Cursor, OpenCode, and QCA Forward (plugins/open-code-review/).

Configuration resolves in this order (per internal/llm/resolver.go): environment variables (OCR_LLM_PROTOCOL etc.) → config.json's llm.protocol (or the legacy use_anthropic boolean) or a named built-in provider preset (anthropic, openai, or a custom provider entry) → the endpoint's model/token. rule.json layers custom → project → global → system rule text, first match wins per file.

4. Trust boundaries & security posture (design-level)

Summarized from the project's own ASSURANCE_CASE.md (source-verified):

5. Quality mechanisms

6. The shared execution engine — internal/llmloop.Runner

Both ocr review and ocr scan dispatch into the same per-file tool-use loop (internal/llmloop.Runner.RunPerFile) rather than each having its own copy — this is the one piece of machinery every review, of either mode, actually runs through.

In plain terms: think of the Runner as a single conversation moderator that both the "diff review" desk and the "full-file scan" desk share. It doesn't know or care which desk called it; it just runs the same loop — send the conversation, execute whatever tools come back, track how big the conversation is getting, stop when the model says it's done or the budget runs out — and reports back what happened.

See data-flow for the artifact-by-artifact flow through this loop, and architecture.html §7 (llmloop box) for the exact stop conditions.