pr-review

Monorepo for PR Review platform — a modern, best-practices TypeScript/Node.js web application, featuring client, server, and shared workspaces with robust tooling for development and code review automation.

---

Screenshot

A sample PR Review session in the app:

Table of Contents

• pr-review
  • Screenshot
  • Table of Contents
  • Project Structure
  • Prerequisites
  • Installation
  • Scripts
    • Build
    • Development
    • Lint & Format
    • Testing
  • Development Usage
  • Key Features
  • Server Configuration & Integrations
    • 1. Point to a Repository
    • 2. GitHub Authentication (Required)
  • Manual LLM Workflow

---

Project Structure

This is a JavaScript/TypeScript monorepo managed with npm workspaces. Each package has its own scope and purpose:

pr-review/
├── packages
│   ├── client   # React web application (Vite, Tailwind)
│   ├── server   # Express-based API server
│   └── shared   # Shared types and logic (used by both client and server)
├── AGENTS.md    # Contributor/agent guidelines and workflows
├── package.json # Monorepo configs and root scripts
└── ...

Prerequisites

• Node.js >=24.9.0

No native dependencies or C++ build tools are required. The server uses Node.js's built-in node:sqlite module (DatabaseSync) for data storage, so SQLite is available out of the box — no compilation step, no platform-specific binaries, and no extra flags needed.

Installation

Clone the repository and install dependencies for all workspaces:

# Clone the repository
git clone https://github.com/your-org/pr-review.git
cd pr-review

# Install dependencies for all packages
npm install

Scripts

All scripts are run from the monorepo root. (See package.json for more details.)

Build

npm run build          # Build all packages

• To build only one package:

npm run build -w packages/client   # or server, shared

Development

npm run dev            # Run client and server in watch mode (concurrently)

Or run each workspace individually:

npm run dev -w packages/client     # Start client (Vite)
npm run dev -w packages/server     # Start server (Express)

Lint & Format

npm run lint           # Lint codebase with Biome
npm run lint:fix       # Auto-fix lint errors
npm run format         # Format codebase
npm run format:check   # Check formatting

Testing

npm test               # Run all tests with Vitest
npm run test:watch     # Watch mode
npm run test:coverage  # Coverage report
npm run test:ui        # Interactive mode (Vitest UI)

Development Usage

• Client: Modern React (18+), Vite, TailwindCSS, React Router, TanStack React Virtual
• Server: Express, TS, node:sqlite (DatabaseSync), Octokit
• Shared: Common types/modules reused on client and server

All apps follow strict TypeScript, formatting and style guidelines (see AGENTS.md for further details).

Key Features

• Tag-based review -- the LLM (or the reviewer manually) splits a PR's diff into thematic tags (e.g., "database", "birthdate-validation-fix", "tests") so the reviewer can examine one concern at a time instead of reviewing files linearly.
• Branch metadata -- the dashboard and review page display source/target branch, commit count, and last sync time for each PR.
• SHA-based git operations -- diffs and logs are computed from exact commit SHAs fetched from GitHub, without creating local branches. This ensures reproducibility even when the target branch advances.
• Manual LLM workflow -- download a self-contained tagging prompt, paste it into any LLM (e.g., VS Code Copilot Chat, ChatGPT), and upload the JSON result back into the app. See Manual LLM Workflow for details.

Server Configuration & Integrations

The server requires additional setup for repository targeting and GitHub authentication.

1. Point to a Repository

By default, the server uses the current directory as its repository root. To target a different repository, set the REPO_PATH environment variable to the absolute path of a cloned Git repository:

REPO_PATH=/absolute/path/to/your/repo npm run dev

• The path must be a local clone of a Git repository with an origin remote set.
• The repository does not need to be checked out at any particular branch. The app fetches exact PR commit SHAs from GitHub and retrieves them from origin as needed — no local branches are created or required, and the working tree state does not matter.
• The SQLite database is automatically created at <REPO_PATH>/.pr-review/data.db inside the target repository folder.

2. GitHub Authentication (Required)

• The server requires access to a valid GitHub authentication token to fetch repository/pull request data.
• Authentication is automatically managed via the GitHub CLI:
  1. Install the gh CLI if not already installed.
  2. Run gh auth login and follow the prompts to authenticate for your target GitHub host (e.g., github.com).
  3. The server will use this token at runtime—no need to manually pass it in most cases.

Manual LLM Workflow

To analyze a PR with an LLM, use the manual workflow:

1. Download the prompt -- on the review page, click "Download Prompt" in the toolbar. This downloads a self-contained .txt file with the full tagging prompt and all diff chunks included.
2. Paste into your LLM -- open the .txt file and paste its contents into your preferred LLM chat interface.
3. Get the JSON response -- the LLM will respond with a JSON object containing tag definitions and chunk assignments. Save this as a .json file, or ask your LLM agent to save the output directly as a JSON file.
4. Upload the results -- back on the review page, click "Upload Results" and select the .json file. The system validates the structure and stores the tags, replacing any existing tags for the affected chunks.

The imported JSON must match the RawTaggingResult format (snake_case fields). The system requires at least 50% of chunks to match by file path and chunk index.