# Code Review System Low-Level Design: Diff Engine, Inline Comments, and Review State Machine

Source: https://www.techinterview.org/post/3233469720/lld-code-review-system/
Updated: 2026-06-30 · techinterview.org

## Pull Request Model

A pull request (PR) represents a request to merge a source branch into a target branch. Core fields: `pr_id`, `repo_id`, `source_branch`, `target_branch`, `base_commit_sha` (the common ancestor at PR creation), `head_commit_sha` (latest commit on source branch), `title`, `description`, `author_id`, `status` (`OPEN`, `MERGED`, `CLOSED`), `created_at`. The diff is computed between `base_commit_sha` and `head_commit_sha`.

## Diff Computation

Diffs are computed using the **Myers diff algorithm**, which finds the shortest edit script (minimum insertions and deletions) to transform one file into another. The output is a unified diff: a list of hunks, each hunk being a contiguous region of change. For small changes within a line, a second pass computes character-level highlighting to show exactly which characters changed within a modified line.

Diffs are computed on demand and cached. The cache key is `(base_commit_sha, head_commit_sha, file_path)`. Diffs are invalidated only when new commits are pushed — they are immutable for a given pair of SHAs.

## Diff Storage Format

The structured diff is stored as:


```
[{
  file: "src/auth.py",
  status: "modified" | "added" | "deleted" | "renamed",
  hunks: [{
    old_start: 10, old_lines: 5,
    new_start: 10, new_lines: 7,
    lines: [
      {type: "context", content: "def login():"},
      {type: "deleted", content: "    pass"},
      {type: "added",   content: "    return authenticate()"}
    ]
  }]
}]
```


## Inline Comment Anchoring

Inline comments attach to a specific location: `(file_path, diff_side: old|new, line_number, commit_sha)`. When new commits are pushed and the diff changes, existing comments must be remapped. The algorithm:

- Take the comment's original line number in the old diff

- Walk the new diff's hunk offsets to find where that line moved

- If the line was deleted in the new diff, mark the comment as `outdated` — it remains visible but flagged

- If the line survived, update the comment's line number to the new position

## Comment Threading and State

Comments form threads: a top-level comment plus replies. Thread state: `OPEN` or `RESOLVED`. Resolving a thread collapses it in the diff view but retains it in history. Emoji reactions are stored as a map of `{emoji: [user_ids]}` on each comment record. The PR is blocked from merge if any thread with a required reviewer's comment remains `OPEN`.

## Review State Machine

Each reviewer submits a review with one of three states:

- **APPROVED** — reviewer signs off on the changes

- **CHANGES_REQUESTED** — reviewer requires modifications before merge

- **COMMENT** — reviewer leaves comments without a blocking verdict

Merge eligibility requires: N approvals (configurable per repo), zero active `CHANGES_REQUESTED` reviews, and all required CI checks passing. Pushing new commits dismisses existing approvals (configurable: dismiss all, or dismiss only if relevant files changed).

## CI Status Integration

External CI systems post status checks via a commit status API: `POST /repos/{repo}/statuses/{sha}` with payload `{context: "ci/tests", state: "pending|success|failure", target_url}`. The PR aggregates all required status checks. Required checks are configured per branch protection rule. A PR is blocked from merge until all required checks report `success`.

## Merge Queue

Without a merge queue, two PRs can both pass CI independently then conflict on merge. The merge queue serializes merges:

- Author enqueues the PR (requires all checks green and required approvals)

- Queue manager rebases the PR onto the current target branch tip

- CI runs on the rebased branch

- On CI success, the PR is merged; the next item in the queue is rebased and tested

- On CI failure, the PR is ejected from the queue and the author is notified

## CODEOWNERS and Reviewer Assignment

A `CODEOWNERS` file maps path patterns to required reviewers. When a PR is opened, the system evaluates which paths were changed and automatically assigns the corresponding owners as required reviewers. Multiple patterns can match the same file; all matched owners are required. Ownership is enforced at merge time — a PR touching a file without approval from that file's owner is blocked.

## Draft PRs and Review Reminders

Draft PRs signal work-in-progress: no review requests are sent, merge is blocked regardless of approvals, and CI may optionally skip expensive steps. Converting to ready-for-review triggers reviewer assignment and notifications. Review reminders are sent to assigned reviewers after a configurable inactivity period (default 24 hours) — implemented as a scheduled job that queries for PRs with no reviewer action since the last push.

See also: [Atlassian Interview Guide](https://www.techinterview.org/post/3233459919/atlassian-interview/)

See also: [Netflix Interview Guide 2026: Streaming Architecture, Recommendation Systems, and Engineering Excellence](https://www.techinterview.org/post/3233460274/netflix-interview-guide-2026-streaming-architecture-recommendation-systems-and-engineering-excellence/)

See also: [Scale AI Interview Guide 2026: Data Infrastructure, RLHF Pipelines, and ML Engineering](https://www.techinterview.org/post/3233460275/scale-ai-interview-guide-2026-data-infrastructure-rlhf-pipelines-and-ml-engineering/)