Module docs — index
Every package now has both a standalone Markdown doc (this folder, one file per
package — same plain-English-first/technical-second format as VVAH's docs/modules/*.md)
and an entry in the interactive architecture.html §7
"Module Flow" (click any box to expand it). Both are generated from the same single source
of truth, tools/ocr_module_data.py — edit that file's
MODULES list to change any module's narrative, then re-run both
tools/generate_architecture_html.py and
tools/gen_module_docs.py. Never hand-edit a file in this
folder directly (rule 9 in the Visa project's templates/README.md): a later regeneration
would silently overwrite the patch.
The thirteen packages, by layer
| Layer | Package | Doc | One-line plain-English role |
|---|---|---|---|
| 1 · Entry | cmd/opencodereview/ |
cli.md |
Parses the command, resolves which LLM to call, wires everything else together. |
| 2 · Change selection (deterministic) | internal/diff/ |
diff.md |
Turns "what changed" into a precise per-file diff — no model involved. |
| 2 · Change selection (deterministic) | internal/config/{rules,allowlist,template,toolsconfig} |
config_rules.md |
Decides which files are eligible and which rule text each one sees. |
| 3 · Orchestration | internal/agent/ |
agent.md |
Runs ocr review: one goroutine per changed file, tracks coverage. |
| 3 · Orchestration | internal/scan/ |
scan.md |
Runs ocr scan: same pattern, whole files instead of diffs. |
| 3 · Orchestration | internal/delegate/ |
delegate.md |
Runs ocr delegate: hands the review to your own coding agent — no LLM call here. |
| 4 · Execution loop | internal/llmloop/ |
llmloop.md · HTML |
The one shared tool-use conversation loop review and scan both dispatch into. |
| 5 · Tools & extensibility | internal/tool/ |
tool.md · HTML |
The six built-in tools the model can call. |
| 5 · Tools & extensibility | internal/mcp/ |
mcp.md |
Lets external MCP servers add more tools, indistinguishable from built-ins. |
| 6 · Model transport | internal/llm/ |
llm.md · HTML |
Decides which provider/protocol/model a run actually talks to, and how retries work. |
| 7 · Persistence & observability | internal/session/ |
session.md |
The audit trail — history, coverage manifest, resume matching. |
| 7 · Persistence & observability | internal/viewer/ |
viewer.md |
A local web page for browsing a past session. |
| 7 · Persistence & observability | internal/telemetry/ |
telemetry.md |
Opt-in OpenTelemetry instrumentation, never load-bearing. |
The three packages that actually carry a model call end to end (llmloop, tool, llm —
the ones a reader asking "where's the AI" cares about most) also ship as styled .html,
same choice VVAH made for its backends/remediation_agent/validation modules.
Reading order by role
- Non-technical reader:
architecture.html, Simple mode, §1 → §3 → §9. - Junior developer: HLD → LLD → the module doc
for the package you're about to touch →
architecture.html§7 (Technical mode) to see it next to its dependencies. - Security reviewer: HLD §4
(trust boundaries) →
tool.md,llm.md,viewer.md→samples/open-code-review/ASSURANCE_CASE.md(the primary source those sections summarize). - Anyone asking "does this use LangChain/LangGraph?" → LLD §12
— verified finding: no, OCR's tool-use loop is hand-rolled Go (
llmloop.md), unlike VVAH's DeepAgents/LangGraph-based S10/S11 runtime. - Anyone deciding where to make a change:
tool-outputs/codegraph/module_dependencies.json— real call-graph edges, so you can see what a package actually depends on before editing it.