# Open-Code-Review Architecture: Inside Alibaba's Modular Go CLI

> Explore the Open-Code-Review architecture: four layers enabling deterministic file selection and LLM-powered code reviews via a Cobra Go CLI from Alibaba.

- Repository: [Alibaba/open-code-review](https://github.com/alibaba/open-code-review)
- Tags: architecture
- Published: 2026-08-04

---

**Open-code-review architecture consists of four tightly-coupled layers—CLI dispatch, domain logic, runtime engine, and supporting services—that orchestrate deterministic file selection and LLM-powered code reviews through a Cobra-based Go CLI.**

The open-code-review architecture follows a modular design pattern that separates deterministic engineering concerns from dynamic AI operations. Developed by Alibaba as a Go-based CLI tool, the codebase structures functionality into distinct layers responsible for command routing, review orchestration, manifest tracking, and auxiliary services. This architectural separation ensures that the **LLM never decides which files to review**; instead, the CLI maintains hard-constraint coverage through deterministic selection and rule resolution.

## CLI Entry Point and Command Dispatch

The architecture centers on **Cobra** for command parsing and dispatch. The [`root.go`](https://github.com/alibaba/open-code-review/blob/main/root.go) file in `cmd/opencodereview/` defines the top-level `ocr` command and registers all sub-commands through `rootCmd.AddCommand()`.

```go
rootCmd.AddCommand(versionCmd)      // ocr version
rootCmd.AddCommand(reviewCmd)       // ocr review
rootCmd.AddCommand(scanCmd)         // ocr scan
rootCmd.AddCommand(delegateCmd)     // ocr delegate …
rootCmd.AddCommand(sessionCmd)      // ocr session …
rootCmd.AddCommand(configCmd)       // ocr config …
rootCmd.AddCommand(viewerCmd)       // ocr viewer

```

*Source*: [[`cmd/opencodereview/root.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/root.go)](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/root.go)

This layer handles user input parsing, version output, and routes execution to the appropriate domain command handler.

## Domain Logic Layer

The domain logic implements six primary commands, each residing in its own file within `cmd/opencodereview/`. These handlers bridge CLI arguments to the runtime engine.

### Review and Scan Commands

The **`review`** command drives the core AI-powered workflow. It reads Git diffs, resolves target files, and invokes the LLM agent to generate line-level comments. Implementation resides in [`cmd/opencodereview/review_cmd.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/review_cmd.go).

The **`scan`** command performs full-file scans without Git diff constraints, designed for auditing unfamiliar codebases. This logic lives in [`cmd/opencodereview/scan_cmd.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/scan_cmd.go).

### Delegation and Session Management

The **`delegate`** command switches the tool into **Delegation Mode**, where an external coding agent executes the review while open-code-review handles only deterministic selection and rule resolution. See [`cmd/opencodereview/delegate_cmd.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/delegate_cmd.go).

The **`session`** command persists run states—manifests, checkpoints, and comments—to `~/.ocr/sessions/`. It enables resume functionality and historical inspection via `ocr session list` and `ocr session comments`. Implementation is in [`cmd/opencodereview/session_cmd.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/session_cmd.go).

### Configuration and Viewer

The **`config`** command manages provider selection (Claude, Codex, Cursor), API key storage, and runtime options through a JSON configuration at `$HOME/.ocr/config.json`.

The **`viewer`** command launches an embedded HTTP server for browsing review results in a browser, implemented across [`cmd/opencodereview/viewer_cmd.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/viewer_cmd.go) and [`internal/viewer/server.go`](https://github.com/alibaba/open-code-review/blob/main/internal/viewer/server.go).

## Runtime Engine: The ManifestBuilder

The **ManifestBuilder** in [`internal/session/manifest.go`](https://github.com/alibaba/open-code-review/blob/main/internal/session/manifest.go) forms the deterministic core of the open-code-review architecture. It tracks coverage, persists run manifests, and enforces the constraint that file selection remains strictly deterministic.

- **Item Identification**: The `ItemID(operation, mode, oldPath, newPath)` function generates stable hashes that survive resume cycles.
- **Lifecycle Methods**: The builder follows a strict sequence: `RegisterSelected` → `SealSelected` → `Mark*` (Completed/Failed/Waived) → `Finalize`.
- **Failure Handling**: Per-item `FailureClass` and run-level `RunFailureClass` categorize failures (provider errors, timeouts) in the final `RunManifest`.

The builder uses a mutex for **concurrent-safety** and maintains **idempotency**—re-applying the same outcome does not corrupt state.

## Supporting Services

Four service categories support the core workflow:

- **Viewer** ([`internal/viewer/server.go`](https://github.com/alibaba/open-code-review/blob/main/internal/viewer/server.go)): Serves static assets and HTML templates while enforcing host-header allowlists to prevent DNS-rebinding attacks.
- **Telemetry** (`internal/telemetry/*`): Emits OpenTelemetry spans and metrics integrated with the manifest lifecycle.
- **Toolset** (`internal/tool/*`): Provides utilities for code search, comment collection, file reading, and diff handling that the LLM agent invokes during reviews.
- **Session Persistence** (`internal/session/*`): Stores run manifests and checkpoints under the user's session directory.

## Execution Flow Example

A typical review workflow demonstrates how the architectural layers interact:

1. **CLI** parses `ocr review` and invokes `reviewCmd` from [`cmd/opencodereview/review_cmd.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/review_cmd.go).
2. **Git diff** generation feeds target files to `ManifestBuilder.RegisterSelected`.
3. `SealSelected` locks the denominator, establishing the coverage boundary.
4. The **LLM agent** receives per-file prompts and requests additional context via the **toolset**.
5. The CLI calls `MarkCompleted`, `MarkFailed`, or `MarkWaived` for each file based on agent results.
6. `Finalize` produces a JSON `RunManifest` persisted to the session store.
7. Optionally, `viewerCmd` launches the embedded server, loading the manifest to display grouped comments and severity statistics.

```bash

# Configure a provider

ocr config provider

# Run review on current workspace

ocr review

# View results in browser

ocr viewer  # starts http://localhost:8080

```

## Summary

- **Four-layer architecture**: CLI dispatch, domain logic, runtime engine (ManifestBuilder), and supporting services.
- **Deterministic coverage**: The ManifestBuilder enforces hard constraints on file selection, ensuring the LLM only reviews CLI-selected files.
- **Command modularity**: Each command (review, scan, delegate, session, config, viewer) resides in dedicated files under `cmd/opencodereview/`.
- **State management**: Sessions persist to `~/.ocr/sessions/` with idempotent, concurrent-safe manifest operations.
- **Extensibility**: The toolset and telemetry layers allow integration with multiple LLM providers and observability platforms.

## Frequently Asked Questions

### What is the ManifestBuilder in open-code-review architecture?

The **ManifestBuilder** is the deterministic core located in [`internal/session/manifest.go`](https://github.com/alibaba/open-code-review/blob/main/internal/session/manifest.go) that tracks which files are selected for review and their eventual outcomes. It generates stable `ItemID` hashes for each file and maintains lifecycle state through methods like `RegisterSelected`, `SealSelected`, and `Finalize`, ensuring complete auditability of the review process.

### How does open-code-review architecture support multiple LLM providers?

The architecture abstracts provider configuration through the `config` command and domain logic layer. The [`cmd/opencodereview/config_cmd.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/config_cmd.go) handles interactive provider selection (Claude, Codex, Cursor) and API key storage in `$HOME/.ocr/config.json`. The runtime engine remains provider-agnostic, treating the LLM as an external agent that receives prompts and returns structured comments.

### What is Delegation Mode in the open-code-review architecture?

**Delegation Mode**, implemented in [`cmd/opencodereview/delegate_cmd.go`](https://github.com/alibaba/open-code-review/blob/main/cmd/opencodereview/delegate_cmd.go), is an architectural variant where open-code-review performs only deterministic file selection and rule resolution while handing actual review execution to an external coding agent. This mode separates concerns when users want to use their own AI agents while retaining open-code-review's coverage tracking and manifest generation.

### How does the viewer component work within the open-code-review architecture?

The **viewer** is a supporting service that launches an embedded HTTP server via [`internal/viewer/server.go`](https://github.com/alibaba/open-code-review/blob/main/internal/viewer/server.go). It serves HTML templates and static assets to display review sessions, grouping comments by file and showing severity statistics. The server includes security measures such as host-header allowlists to prevent DNS-rebinding attacks, and it reads persisted manifests from the session store to render historical review data.