Production Deployment Guide

Relevant source files

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

• README.md
• turbo.json
• package.json
• apps/web/app/api/webhooks/github/route.ts
• packages/db/prisma/schema.prisma
• packages/review/src/orchestrator.ts
• apps/web/README.md

This guide outlines the architecture and requirements for deploying the AI Code Reviewer system into a production environment. The system is designed as a decoupled, multi-process architecture that leverages PostgreSQL for both persistent storage and background job queue management.

System Architecture

The production environment consists of two primary Node.js processes sharing a single PostgreSQL database. This separation ensures that high-latency tasks, such as LLM processing, do not block the high-availability requirements of the web server receiving GitHub webhooks.

Component Overview

• apps/web (Next.js Server): Handles incoming HTTP requests, GitHub OAuth, and webhook intake. It is optimized for low latency and enqueues background jobs.
• apps/worker (Node.js Worker): A background process that polls the pg-boss queue to execute long-running tasks like code analysis and LLM interactions.
• PostgreSQL Database: Serves as the primary data store and the job queue backend (using the pgboss schema).

Infrastructure Requirements

Database

The system requires PostgreSQL with the pgvector extension enabled to support semantic search and RAG (Retrieval-Augmented Generation) features.

• Extensions: pgvector is mandatory for the ChunkEmbedding and ReviewMemoryEmbedding models.
• Schema Management: Prisma is used for migrations and client generation.

Sources: packages/db/prisma/schema.prisma:10-13, README.md:120-130

Environment Variables

A standard set of environment variables must be configured across both services.

Variable	Requirement	Description
DATABASE_URL	Required	PostgreSQL connection string
ENCRYPTION_KEY	Required	64 hex chars (32 bytes) for AES-256-GCM encryption of stored secrets
SESSION_SECRET	Required	64 hex chars for JWT session signing
GITHUB_APP_PRIVATE_KEY	Required	PEM private key for GitHub App authentication
GITHUB_WEBHOOK_SECRET	Required	Secret for HMAC signature verification
OPENAI_API_KEY	Required	API key for LLM operations

Sources: README.md:275-300, turbo.json:6-25

Deployment Strategy

The application is containerized and can be deployed using Docker. In production, apps/web and apps/worker should be scaled independently based on load.

Build and Run

The project uses a monorepo structure managed by Turborepo. Both applications are typically built from the same Docker image but started with different entry points.

# Build the entire project
docker compose build

# Recommended Production Start for Web
npm run start -w web

# Recommended Production Start for Worker
npm run start -w worker

Scaling Considerations

• Web Server: Scale horizontally based on Requests Per Second (RPS). Ensure it remains lightweight.
• Worker: Scale based on queue depth. Since LLM calls take 5-30 seconds, the worker pool must be large enough to handle peak PR activity without exceeding LLM rate limits.

Sources: README.md:310-320, package.json:6-15

Webhook Handling and Idempotency

Production deployment requires robust webhook handling. GitHub re-delivers webhooks on timeouts; the system implements deduplication via the WebhookDelivery table.

Security Configuration

1. HMAC Verification: The GITHUB_WEBHOOK_SECRET must be used to verify x-hub-signature-256 headers using timingSafeEqual to prevent timing attacks.
2. Secret Encryption: User-supplied API keys (for BYO-LLM features) must be encrypted at rest using the @repo/crypto package before storage in the ProviderCredential table.
3. Payload Limits: The web server enforces a MAX_PAYLOAD_BYTES limit (25 MB) to prevent denial-of-service through large webhook payloads.

Sources: apps/web/app/api/webhooks/github/route.ts:40-60, README.md:165-170, packages/db/prisma/schema.prisma:243-265

Monitoring and Maintenance

• Logging: The system uses Pino for structured JSON logging. Logs include correlationId and aiReviewId to trace requests through the web-to-worker pipeline.
• Database Cleanup: WebhookDelivery and AiReview records should be monitored to ensure the database size remains manageable over time.
• Prisma Migrations: Run npx prisma migrate deploy as part of the CI/CD pipeline before the application services start.

Sources: README.md:180-190, README.md:260-265

Conclusion

A production-ready deployment of the AI Code Reviewer requires a specialized PostgreSQL environment, a decoupled process model for web and worker, and strict adherence to security protocols regarding webhook verification and secret encryption. This architecture ensures the system can handle the high-latency demands of AI processing while remaining responsive to GitHub's infrastructure.