CodeReview - AI-Powered GitHub PR Reviewer

A GitHub PR reviewer that provides automated static analysis, AI critique, and policy-based gating for pull requests.

Architecture

graph TD
    %% Top-level orientation
    %% Clients and GitHub
    subgraph "Clients & GitHub"
        GH[GitHub Repos & PRs]
        DEV[Developers]
        GH -->|Webhooks: PR events| API[Webhook API:<br/>Node.js, Fastify]
        API -->|Checks API<br/>status/annotations| GH
    end

    %% Control plane: queue + db
    subgraph "Control Plane"
        API -->|Enqueue Job| Q[(Redis Queue)]
        Q -->|BRPOP Job| W[Analyzer Worker:<br/>Python]
        API --> DB[(PostgreSQL)]
    end

    %% Analysis workers and tools
    subgraph "Analysis"
        W --> CLONE[Git Checkout<br/>base/head]
        W --> SEMG[Semgrep]
        W --> ESL[ESLint]
        W --> BAN[Bandit]
        SEMG --> FND[Findings]
        ESL --> FND
        BAN --> FND
    end

    %% Storage / artifacts
    subgraph "Artifacts & Storage"
        W --> MINIO[(MinIO / S3)]
        W --> DB
    end

    %% Observability
    subgraph "Observability"
        API --> PMET[Prometheus Metrics]
        W --> PMET
        PMET --> PROM[Prometheus]
        PROM --> GRAF[Grafana]
    end

    %% Health
    subgraph "Health"
        API --> H["/health, /metrics"]
        W --> H
    end

Loading

End-to-End PR Flow

sequenceDiagram
    autonumber
    participant GH as GitHub
    participant API as Webhook API (Node/TS)
    participant Q as Redis Queue
    participant W as Analyzer Worker (Python)
    participant T as Static Tools (Semgrep / ESLint / Bandit)
    participant S as MinIO (Artifacts)
    participant DB as PostgreSQL
    participant Checks as GitHub Checks

    GH->>API: 1) pull_request opened/synchronize
    API->>API: 2) Verify HMAC • rate-limit • upsert repo/PR
    API->>Q: 3) enqueue(job)
    W-->>Q: 4) BRPOP(job)
    W->>GH: 5) git fetch/checkout base & head
    W->>T: 6) run analyzers (diff-aware)
    T-->>W: 7) findings (SARIF/Markdown)
    W->>S: 8) upload artifacts
    W->>DB: 9) persist run & findings
    W->>Checks: 10) create/update Check Run summary
    Checks-->>GH: 11) status + annotations appear on PR

Loading

---

Component Responsibilities (quick scan)

• Webhook API (Node/TS + Fastify): Validates GitHub webhooks, enforces rate limits & policies, persists metadata, enqueues jobs, and reports status via Checks API.
• Analyzer Worker (Python): Checks out the PR diff, runs Semgrep/ESLint/Bandit, aggregates results (Markdown + SARIF), uploads artifacts to MinIO, persists runs/findings to PostgreSQL, and updates GitHub Checks.
• Queue (Redis): Simple RPUSH/BRPOP work queue for reliable, decoupled processing.
• Storage: PostgreSQL for relational data and MinIO/S3 for artifacts.
• Observability: Prometheus metrics and Grafana dashboards; health endpoints exposed on services.

Features

• Real-time Analysis: Automatic code review on every pull request
• Static Analysis: Semgrep, ESLint, Bandit integration
• AI Critique: Optional AI-powered code review
• Policy Engine: Configurable rules for blocking/approving PRs
• GitHub Integration: Native GitHub App with Checks API
• Slack Notifications: Real-time notifications for blocked PRs
• Observability: Prometheus metrics and Grafana dashboards

Quick Start

# Clone and setup
git clone https://github.com/sarihammad/codereview.git
cd codereview
cp .env.example .env
# Edit .env with your configuration

# Start development environment
make demo

# Run smoke test
make smoke

3 Commands to Run

# 1. Start services
make dev-up

# 2. Run complete demo
make demo

# 3. View results
# Check Grafana: http://localhost:3000 (admin/admin)
# Check Prometheus: http://localhost:9090
# Check webhook API: http://localhost:8080/health

Tech Stack

• Webhook API: Node.js 20 + TypeScript (Fastify)
• Analyzer Worker: Python 3.11
• Queue: Redis (RPUSH/BRPOP)
• Static Tools: Semgrep, ESLint, Bandit
• Storage: PostgreSQL 15, MinIO/S3
• Observability: Prometheus + Grafana
• CI/CD: GitHub Actions

Documentation

• Setup Guide - GitHub App configuration
• Architecture - System design and components
• API Reference - Complete API documentation
• Deployment - Production deployment guide
• Observability - Monitoring and dashboards
• Rulebook - Static analysis rules and configurations

Testing

# Run all tests
make test

# Run specific test suites
make test-webhook
make test-analyzer

# Smoke test
make smoke

Monitoring

• Health Check: http://localhost:8080/health
• Metrics: http://localhost:8080/metrics
• Grafana: http://localhost:3000 (admin/admin)

Development

# Start development environment
make dev-up

# Run linters
make lint

# Run type checking
make type

# Stop environment
make dev-down

License

MIT License - see LICENSE file.