Design · Open Code Review (OCR)

Data Flow (DFD)

↩ architecture.html · generated 2026-08-14

Data Flow (DFD)

This document traces what data moves through Open Code Review (OCR), at three levels of zoom. The labelled artifact on each arrow is the most useful thing to memorize as a newcomer.

Rendered images: 03_context_dfd.svg (L0), 02_dataflow_pipeline.svg (L1, ocr review), 05_scan_and_delegate.svg (ocr scan / ocr delegate).

Data enters as a git diff (or whole files). It is progressively refined: a raw diff becomes a filtered, per-file work item; a work item becomes a conversation; a conversation becomes zero or more tool calls; a code_comment tool call becomes a location-checked finding; findings become an optionally-filtered comment set; and the whole run's outcome — per file — becomes a coverage manifest. Nothing skips ahead; each stage consumes the previous stage's artifact.

Level 0 — Context diagram

flowchart LR DEV([Developer / CI job]) -->|ocr review/scan/delegate + config| CLI[OCR CLI] REPO[(Local git repository)] -->|diffs / file contents| CLI CLI -->|diff + prompt| PROV([LLM Provider API]) PROV -->|review comments JSON| CLI CLI -. "rule groups + file selection
(delegate mode)" .-> AGENTPROV([User's own coding agent]) AGENTPROV -. "review comments
(agent's own LLM call)" .-> OUT[[Review output]] CLI -->|comments, SARIF, session JSONL| OUT OUT -->|review| DEV BROWSER([Local browser]) -.->|HTTP, loopback only| CLI

External entities: the developer/CI job, the local git repo, the configured LLM provider, and — only in delegation mode — the user's own coding agent. OCR never writes back to the target repository in any mode (unlike a remediation tool): its only outputs are comments, SARIF, and its own session files.

Level 1 — ocr review data flow

flowchart LR R[(git repo)] -->|GetDiff| D[internal/diff] D -->|"[]model.Diff"| F[Filter: rules/allowlist/size/budget] F -->|per file| DISP[Dispatch: bounded goroutines] DISP -->|diff, rule, plan| PLAN[Plan phase optional] PLAN -->|plan_guidance| LOOP[Main tool-use loop] LOOP <-->|tool calls| TOOLS[file_read/find/search/read_diff] LOOP -->|code_comment| RESOLVE[Line-number resolve/relocate] RESOLVE --> COLLECT[CommentCollector] LOOP -->|task_done| FILTER[Review filter optional] COLLECT --> FILTER FILTER --> OUT[[Terminal / SARIF]] DISP -.->|registerCoverage| MANIFEST[session.Manifest] LOOP -.->|AppendTaskRecord| JSONL[(Session JSONL)] MANIFEST -.-> JSONL

Data stores touched: the session's own JSONL file (one per run, append-only) and the in-memory tool.CommentCollector (drained once per file, or per-run for the review filter pass). There is no shared database across runs — --resume reads a prior run's JSONL directly, matched by session ID.

Artifact reference

Artifact Produced by Consumed by Shape
[]model.Diff internal/diff.Provider.GetDiff agent filtering, dispatch per-file unified diff + insertions/deletions
filtered []model.Diff agent.filterDiffs / filterLargeDiffs dispatch rule/allowlist/size-eligible subset
plan text (optional) Plan phase LLM call main-loop prompt ({{plan_guidance}}) free text
tool call Main loop (model) Runner.executeToolCall llm.ToolCall (name + JSON args)
tool result internal/tool provider main loop (next round) string
model.LlmComment code_comment tool + line resolver CommentCollector, review filter path, line range, category, severity, optional suggestion
session.CoverageItem agent.registerCoverage session.ManifestBuilder item ID, path, content fingerprint
session.RunManifest Agent.finalizeManifest CLI output, --resume frozen coverage snapshot (completed/reused/failed)
Session JSONL session.SessionHistory ocr session show/comments, ocr viewer, --resume append-only task records

Level 2 — ocr scan and ocr delegate

flowchart LR subgraph scan[ocr scan — internal/scan] ENUM[Enumerate files] -->|"[]model.ScanItem"| SPLAN[Plan optional] SPLAN --> SLOOP[Main loop — same Runner as review] SLOOP --> SDEDUP[Dedup task optional, per batch] SDEDUP --> SSUM[Project summary optional, post-run] end subgraph delegate[ocr delegate — internal/delegate] DSEL[Deterministic file selection + rule resolution] --> DRULES[Rule groups, Markdown] DRULES --> DAGENT([User's own coding agent]) end REPO[(git repo / files)] --> ENUM REPO --> DSEL SSUM --> OUT2[[Review comments]] DAGENT -->|"no OCR API key/LLM config needed"| OUT2

ocr scan reuses internal/llmloop.Runner exactly as ocr review does — the only structural difference is the work item (model.ScanItem, whole file content, no diff) and two extra optional phases: a per-batch dedup task (collapses near-duplicate findings across files in the same batch) and a post-run project-summary task (one Markdown summary across all collected comments).

ocr delegate never reaches internal/llmloop at all — it is the one review-producing path in OCR with no LLM client construction. internal/delegate.RuleGroupsMarkdown formats the same rule-resolution output review/scan use internally, but as Markdown for a human or another agent to read, not as a prompt OCR sends anywhere.

Cross-cutting data handling