Engineering Rules & Guidelines

Relevant source files

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

• CLAUDE.md
• README.md
• packages/review/src/orchestrator.ts
• packages/review/src/prompts.ts
• packages/review/src/llm-client.ts
• packages/db/prisma/schema.prisma

Introduction

The Engineering Rules & Guidelines define the architectural standards, development workflows, and coding conventions for the AI Code Reviewer project. The primary purpose of these guidelines is to maintain a high-quality, scalable RAG-powered review system that leverages GitHub App integrations and Large Language Models (LLMs). These rules ensure that all contributions follow the established pattern of separating business logic from infrastructure, maintaining strict data isolation, and ensuring deterministic execution of review pipelines.

Sources: CLAUDE.md:1-10, README.md:1-15

Architectural Principles

The system is built on a decoupled architecture consisting of a web server for HTTP interactions and a background worker for heavy processing.

Separation of Concerns

A strict hierarchy is enforced to maintain code clarity:

1. Route Handlers: Responsible for parsing input and returning results without containing business logic.
2. Services: Contain all core business logic, remaining agnostic of HTTP concepts.
3. Abstraction Packages: All external API calls (GitHub, LLM) must go through dedicated packages like @repo/github and @repo/llm. Raw SDK calls are prohibited in business logic.

Sources: README.md:95-105

Process and Database Isolation

The project utilizes a shared PostgreSQL database using pg-boss for job queuing, eliminating the need for Redis.

• Web Process (apps/web): Handles OAuth, UI, and webhook intake. It must respond within seconds to avoid GitHub timeouts.
• Worker Process (apps/worker): Handles long-running LLM and GitHub API operations.

Sources: README.md:71-88

Development Guidelines

Coding Conventions

• All retrieval functions must be async.
• Vector Search: All vector queries MUST be filtered by repo_id. Mixing context across different repositories is strictly forbidden.
• Secrets Management: Raw tokens must never be stored in the vector database metadata. API keys must be encrypted using AES-256-GCM via the @repo/crypto service before persistence.
• Observability: Use AsyncLocalStorage for request context to carry IDs (request, user, installation) without manual threading.

Sources: CLAUDE.md:175-182, README.md:139-145, README.md:275-280

Dependency Injection

The project avoids magic DI frameworks in favor of manual wiring. A central container in apps/web/src/server/container.ts explicitly instantiates and links dependencies, ensuring full TypeScript inference and readability.

Sources: README.md:90-95

AI Review Pipeline & RAG Standards

The core value of the system is its 4-layer RAG (Retrieval-Augmented Generation) system.

The 4 Layers of Context

Layer	Name	Purpose
Layer 1	Codebase Context	Find similar patterns via AST-based chunking to flag inconsistencies.
Layer 2	Review Memory	Compound knowledge by storing past accepted/dismissed review decisions.
Layer 3	Rules & Standards	Index repo-specific documentation (README, CONTRIBUTING.md) for citation.
Layer 4	Dependency Graph	Analyze blast radius using import parsing to determine impact on critical paths.

Sources: CLAUDE.md:30-75

Prompt Construction and LLM Safety

Prompts must be structured to ensure structured JSON output. The llm-client wraps these calls to provide safety:

• Validation: LLM output must be validated using Zod schemas (e.g., FileReviewOutputSchema).
• Sanitization: Markdown fences (e.g., ```json) must be stripped from responses.
• Fallback: If an LLM response is malformed, the system must return an empty review rather than failing the process.

Sources: packages/review/src/llm-client.ts:15-35, packages/review/src/orchestrator.ts:165-175

Database Schema & Vector Management

The schema is managed via Prisma and utilizes pgvector for semantic search capabilities.

Key Database Models

• Installation: Represents a GitHub account authorizing the app.
• Repository: Stores repo-specific metadata and whether review is enabled.
• AiReview: Tracks the status of a specific review run.
• Chunk: Stores code snippets with tsvector for full-text search and linked ChunkEmbedding for vector search.

Sources: packages/db/prisma/schema.prisma:45-120, packages/db/prisma/schema.prisma:240-270

Severity Guidelines

Reviews must categorize issues according to fixed severity levels:

• INFO: Suggestions or minor improvements.
• WARNING: Potential bugs or code smells.
• ERROR: Definite bugs or security issues.
• CRITICAL: Significant risks such as data loss or security breaches.

Sources: packages/review/src/prompts.ts:12-16, packages/review/src/schemas.ts:12-15

Summary

The Engineering Rules & Guidelines provide a framework for a robust, RAG-enabled code review platform. By adhering to strict process isolation, mandatory vector filtering by repository, and rigorous LLM output validation, the system ensures reliable and context-aware feedback for developers. All changes to the core review logic or chunking strategies must be tested against real PR samples to maintain the integrity of the review memory.

Sources: CLAUDE.md:185-195, README.md:345-355