Start Here — Open Code Review (OCR) Onboarding Guide

docs / 00_START_HERE

← all docs

Start Here — Open Code Review (OCR) Onboarding Guide

Welcome. This documentation set explains Open Code Review (OCR) — Alibaba's open-source AI code review CLI — for new joiners: analysts, junior developers, and non-technical stakeholders alike.

It follows the same documentation methodology used for the Visa Vulnerability Agentic Harness (VVAH) project: every design doc is split into a plain-English first half (with a data-flow diagram) and a technical second half (with per-package detail), and the interactive architecture.html has a Simple/Technical toggle that changes every description on the page at once — so read at whichever depth you need.

Pick your path

You are… Read, in order
Non-technical (PM, analyst, manager) architecture.html (Simple mode) → Overview
Security analyst Overview → Data Flow → HLD §4 Trust Boundaries
Junior developer HLD → LLD → Data Flow → Module docs → architecture.html §7 (Technical mode)
Reviewer / architect HLD → LLD → Graph Intelligence → tool-outputs/ (real dependency data)
Operator (wants to run ocr, not just understand it) Process & Runbooks index → Setup & Credentials → Run a Review or Scan

All of the Markdown pages above also ship as standalone, styled .html copies (docs/01_overview.html, docs/design/HLD.html, docs/design/LLD.html, docs/design/data-flow.html, docs/modules/README.html, docs/tools/graph-intelligence.html) — same visual language as architecture.html, same shared design tokens (tools/design-system/tokens.css, copied verbatim from the Visa project's kit), Mermaid diagrams rendered live via CDN. Open the .html if you'd rather read in a browser than a Markdown viewer; the .md is always the source of truth — regenerate every .html after editing with python3 tools/gen_design_html.py.

What's in this folder

Alibaba -Open COde Review/
├── architecture.html            ← interactive explainer (START HERE, non-technical friendly)
├── docs/
│   ├── 00_START_HERE.md         ← this file
│   ├── 01_overview.md           ← what OCR is, why it exists, glossary
│   ├── design/
│   │   ├── HLD.md / HLD.html     ← High-Level Design (components, trust boundaries)
│   │   ├── LLD.md / LLD.html     ← Low-Level Design (cross-cutting internals)
│   │   └── data-flow.md / .html  ← DFD levels 0/1/2 + narrative
│   ├── modules/README.md/.html   ← per-package index (full narrative lives in architecture.html)
│   ├── modules/<pkg>.md/.html    ← 13 per-package docs (one per internal/ package)
│   ├── process/                  ← how to *operate* OCR (not just understand it)
│   │   ├── 00_process-and-runbooks-index.md
│   │   ├── process-operate-ocr.md    ← SOP: RACI, flow, exceptions, metrics
│   │   ├── process-optimization.md   ← waste analysis + improvement recommendations
│   │   └── runbooks/                 ← setup-and-credentials, run-a-review-or-scan, use-delegation-mode
│   └── tools/graph-intelligence.md/.html ← how the graphs were built (CodeGraph + Graphify)
├── diagrams/                     ← rendered SVG + PNG (architecture, DFDs, module graph) + module-graph.html
├── tool-outputs/                 ← real CodeGraph & Graphify graph exports + README index
├── tools/                        ← reusable generator scripts (regenerate docs/graphs after code changes)
└── samples/open-code-review/     ← pinned local clone of alibaba/open-code-review — the source of truth

The one-paragraph summary

OCR reads a git diff (ocr review) or whole files (ocr scan), hands each file to an AI agent that can call tools (read other files, search the codebase) before writing a comment, and checks every comment's line number against the real diff before accepting it. Its core design bet is deterministic engineering + agent hybrid: file selection, rule matching, and comment-location checking are plain code with zero model calls; only the actual judgment of "is this a defect" is left to the AI. A third mode, ocr delegate, skips OCR's own AI call entirely and hands file selection + rules to the user's own coding agent (Claude Code, Codex, Cursor) — no OCR-managed API key needed.

OCR only ever reads the repository under review — no mode writes back to your code. ocr review/ocr scan do send diff/file content to your configured LLM provider over HTTPS; ocr delegate sends nothing to an OCR-configured provider at all.

Diagram index

Regenerating after a code change

# 1. refresh the pinned source clone
rsync -a --exclude .git <path-to-open-code-review-repo>/ samples/open-code-review/

# 2. refresh graph data (see docs/tools/graph-intelligence.md for the local-disk caveat)
python3 tools/gen_module_dependencies.py --db <local>/.codegraph/codegraph.db \
  --out tool-outputs/codegraph/module_dependencies.json

# 3. re-render diagrams (edit diagrams/src/*.dot first if structure changed)
for f in diagrams/src/*.dot; do
  b=$(basename "$f" .dot)
  dot -Tsvg "$f" -o "diagrams/$b.svg"
  dot -Tpng -Gdpi=150 "$f" -o "diagrams/$b.png"
done

# 4. regenerate the interactive explainer (edit tools/generate_architecture_html.py's
#    MODULES/SECTIONS/STAGES first if the narrative changed)
python3 tools/generate_architecture_html.py

# 5. regenerate the styled HTML copies of every design/module Markdown doc
#    (edit the .md first — never hand-edit the .html output)
python3 tools/gen_design_html.py