Code Review Pipeline Orchestration

Relevant source files

The following files were used as context for generating this wiki page:

• packages/review/src/orchestrator.ts
• packages/review/src/llm-client.ts
• packages/review/src/prompts.ts
• packages/ingestion/src/process-webhook.ts
• packages/github/src/review-client.ts
• packages/db/prisma/schema.prisma
• README.md

The Code Review Pipeline Orchestration system manages the end-to-end lifecycle of an automated AI code review. It encompasses the transition from a GitHub webhook event to the generation of inline code comments and a final summary posted back to the Pull Request (PR). The system is designed to be asynchronous, resilient, and context-aware, leveraging Large Language Models (LLMs) and Retrieval-Augmented Generation (RAG) to provide high-quality feedback.

Sources: README.md:12-42, packages/review/src/orchestrator.ts:25-45

Pipeline Architecture

The orchestration logic is split between a webhook intake process and a background worker. This separation ensures that GitHub's webhook timeout limits are met while allowing the time-intensive LLM analysis to proceed independently.

High-Level Component Flow

The following diagram illustrates the lifecycle of a review from initial trigger to completion:

The system uses pg-boss as the job queue and PostgreSQL as the primary data store for both the queue and review state.

Sources: README.md:46-95, packages/ingestion/src/process-webhook.ts:85-155

Orchestration Logic

The core orchestration resides in the handleReviewPr function, which manages the AiReview record's state transitions and executes the runReview logic.

Review States

The AiReview record tracks the progress of the pipeline through several statuses defined in the Prisma schema:

Status	Description
PENDING	Review record created, waiting for worker pickup.
RUNNING	Orchestrator has started processing file diffs.
COMPLETED	Comments and summary successfully posted to GitHub.
FAILED	An error occurred during processing; error details are stored.
SKIPPED	Review bypassed due to configuration (e.g., ignored author or path).

Sources: packages/db/prisma/schema.prisma:418-426, packages/review/src/orchestrator.ts:47-73

Execution Steps

1. State Initialization: The orchestrator loads the AiReview record and updates its status from PENDING to RUNNING.
2. Configuration Loading: Retrieves ReviewConfiguration for the specific repository or installation to determine ignorePaths, maxFilesPerPr, and enabled status.
3. Context Gathering: Fetches PR metadata and changed files using the GitHub API.
4. File Filtering: Excludes removed files, binary files, and those matching ignorePaths.
5. Multi-Layer Retrieval (RAG): For each file, the system optionally retrieves similar code from the indexed codebase (Layer 1) and past review decisions (Layer 2) to inject into the LLM prompt.
6. LLM Review: Calls the ReviewLLMClient to analyze the file diff and generate structured comments.
7. Summary and Posting: Aggregates all valid comments, generates a PR-level summary, and posts a single review to GitHub via createPRReview.

Sources: packages/review/src/orchestrator.ts:87-225, packages/github/src/review-client.ts:135-163

Context Layers and RAG Integration

The pipeline enhances LLM analysis by providing four layers of context. Currently, the orchestrator implements Layer 1 and Layer 2 retrieval during the per-file review loop.

Context Types

• Layer 1 (Codebase): Retrieves top 5 similar code patterns from the repository to ensure consistency.
• Layer 2 (Review Memory): Retrieves past review decisions (Accepted/Dismissed) to avoid re-flagging dismissed issues.
• Layer 2 (Repo Knowledge): Injects specific domain knowledge extracted from previous developer feedback.

Sources: packages/review/src/orchestrator.ts:153-193, packages/review/src/prompts.ts:40-66

Data Structures and Validation

The pipeline strictly validates data between components using Zod schemas to prevent LLM hallucinations from causing GitHub API failures.

Key Data Objects

Object	Source	Purpose
FileReviewComment	schemas.ts	Validates line number, severity (INFO/WARNING/ERROR/CRITICAL), and body.
PRFile	review-client.ts	Represents file metadata and diff patch from GitHub.
AiReviewComment	schema.prisma	DB model for storing generated comments.

The system performs a critical "Commentable Line" check. Every comment generated by the LLM is checked against the set of lines present in the diff (added or context lines) using the isCommentableLine utility before being included in the GitHub payload.

Sources: packages/review/src/schemas.ts:15-27, packages/review/src/orchestrator.ts:200-211, packages/github/src/review-client.ts:44-65

Conclusion

Code Review Pipeline Orchestration is a resilient, job-driven system that transforms raw GitHub events into contextualized AI feedback. By decoupling intake from execution and implementing rigorous validation and RAG-based context retrieval, the pipeline ensures that code reviews are both technically accurate and aligned with specific repository standards.

Sources: README.md:120-140, packages/review/src/orchestrator.ts:245-255