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

By /
⏱ 6 min read

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:

  1. Take the comment's original line number in the old diff
  2. Walk the new diff's hunk offsets to find where that line moved
  3. If the line was deleted in the new diff, mark the comment as outdated — it remains visible but flagged
  4. 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:

  1. Author enqueues the PR (requires all checks green and required approvals)
  2. Queue manager rebases the PR onto the current target branch tip
  3. CI runs on the rebased branch
  4. On CI success, the PR is merged; the next item in the queue is rebased and tested
  5. 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

See also: 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

Scroll to Top