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
(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
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
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
- No target-repo writes. Every mode is read-only against the repository under review — OCR's only write targets are the terminal, SARIF output, and its own session directory.
- Comment location is checked, not trusted.
code_comment's line numbers are resolved deterministically against the real diff (diff.ResolveComment); only if that fails does a dedicated re-location LLM call run — the deterministic path is the default, not the fallback. - Token & cost accounting is aggregated per run on
llmloop.Runner(input/output/cache read/cache write tokens) and can gate dispatch via--max-tokens-budget. - Redaction: API keys are read only from environment variables and are explicitly kept
out of logs, session files, and telemetry (
ASSURANCE_CASE.mdT2). - Manifest as audit trail: every dispatchable file is registered before dispatch
starts (
registerCoverage/SealSelected), so the coverage denominator is fixed up front — a run can't under-report what it skipped.