CodeSage 🧙‍♂️

AI-Powered Code Review Assistant for GitHub Pull Requests

Automate code reviews with AI - catch bugs, improve quality, and maintain best practices effortlessly.

Features • Architecture • Quick Start • Documentation

</div>

🎯 Overview

CodeSage is a production-ready AI code review automation platform that integrates with GitHub to provide instant, intelligent feedback on Pull Requests.

Why CodeSage?

The Problem:

Manual code reviews are time-consuming and inconsistent
Junior developers don't get timely feedback
Security vulnerabilities slip through during busy periods
Best practices aren't enforced uniformly

The Solution:

✅ Instant Reviews - AI analysis within seconds of PR creation
✅ Consistent Quality - Every PR gets the same thorough review
✅ Learning Tool - Developers improve from AI suggestions
✅ Focus on What Matters - Seniors review architecture, AI handles syntax

✨ Key Features

🤖 AI-Powered Analysis

Multi-Provider Support: OpenAI GPT-4 with Claude fallback
Comprehensive Checks: Security, performance, bugs, code quality, documentation
Structured Feedback: Categorized by severity (Critical → Info)
Actionable Suggestions: Specific recommendations for fixes

🔗 GitHub Integration

Automatic Webhooks: Triggers on PR creation/update
GitHub App Authentication: Secure JWT-based auth
Direct PR Comments: AI posts formatted reviews as comments
Repository Flexibility: Works across multiple repos

📊 Analytics Dashboard

Real-time Metrics: Quality scores, issue counts, active PRs
Historical Tracking: Review history and trends
Issue Breakdown: By type and severity
Live Updates: Auto-refresh every 30 seconds

🔄 Asynchronous Processing

RabbitMQ Queue: Non-blocking webhook responses
Scalable Architecture: Handles high PR volumes
Retry Logic: Exponential backoff for resilience
Error Recovery: Graceful failure handling

🏗️ Architecture

graph TB
    subgraph "External Services"
        A[GitHub]
        B[OpenAI/Claude API]
    end
    
    subgraph "CodeSage Backend"
        C[Webhook Controller<br/>:8080/api/webhook/github]
        D[RabbitMQ Producer]
        E[Analysis Queue]
        F[RabbitMQ Consumer]
        G[AI Service]
        H[GitHub Service]
        I[Review Repository]
    end
    
    subgraph "Infrastructure"
        J[(PostgreSQL<br/>Database)]
        K[RabbitMQ<br/>Message Broker]
    end
    
    subgraph "Frontend"
        L[React Dashboard<br/>:5173]
    end
    
    A -->|Webhook POST| C
    C -->|Enqueue| D
    D -->|Publish| E
    E -->|Consume| F
    F -->|Analyze| G
    G -->|API Call| B
    B -->|AI Response| G
    F -->|Fetch Diff| H
    H -->|API Call| A
    G -->|Post Comment| H
    H -->|Comment| A
    F -->|Save| I
    I -->|Store| J
    L -->|Fetch Data| I
    
    style A fill:#f9f,stroke:#333,stroke-width:2px
    style G fill:#9cf,stroke:#333,stroke-width:2px
    style J fill:#fcf,stroke:#333,stroke-width:2px
    style K fill:#ffc,stroke:#333,stroke-width:2px

Technology Stack

| Component | Technology | Purpose | |-----------|-----------|---------| | Backend | Spring Boot 3.2 + WebFlux | RESTful API, async HTTP calls | | Frontend | React 18 + Vite | Modern dashboard UI | | Database | PostgreSQL 15 | Persistent data storage | | Message Queue | RabbitMQ 3 | Asynchronous event processing | | AI Engine | OpenAI GPT-4 / Claude | Code analysis | | Authentication | JWT (jjwt) | GitHub App authentication | | Containerization | Docker + Docker Compose | Deployment | | CI/CD | GitHub Actions | Automated testing & builds |

🚀 Quick Start

Prerequisites

Java 17+
Node.js 18+
Docker & Docker Compose
OpenAI or Claude API key

1. Clone & Configure

git clone https://github.com/albonidrizi/CodeSage.git
cd CodeSage

# Copy environment template
cp .env.example .env

# Edit .env with your API keys
nano .env

2. Start with Docker

# Start all services (PostgreSQL, RabbitMQ, Backend, Frontend)
docker-compose up -d

# View logs
docker-compose logs -f

3. Access the Application

Dashboard: http://localhost:80
Backend API: http://localhost:8080/api/reviews/health
RabbitMQ Management: http://localhost:15672 (guest/guest)

💡 Development Mode: The frontend automatically displays demo data when the backend is not available. This allows you to preview the UI without setting up the full infrastructure. To connect to the real backend, ensure PostgreSQL and RabbitMQ are running.

4. Test Locally

# Send test webhook
Invoke-WebRequest -Uri "http://localhost:8080/api/webhook/github" `
  -Method POST `
  -Headers @{"X-GitHub-Event"="pull_request"} `
  -ContentType "application/json" `
  -Body '{"action":"opened","pull_request":{"number":1,"title":"Test PR"}}'

📚 Documentation

Setup Guides

GitHub Integration - Set up GitHub App for real PR reviews
Deployment Guide - Deploy to Railway, Render, or VPS

API Documentation

REST Endpoints

GET  /api/reviews              # List all reviews (paginated)
GET  /api/reviews/{id}         # Get specific review
GET  /api/reviews/repo/{owner}/{name}  # Reviews for repository
GET  /api/reviews/recent       # Last 7 days
GET  /api/reviews/stats        # Dashboard statistics
GET  /api/reviews/health       # Health check

Example Response

{
  "id": 1,
  "repositoryOwner": "yourusername",
  "repositoryName": "your-repo",
  "prNumber": 42,
  "prTitle": "Add new feature",
  "qualityScore": 8.5,
  "status": "COMPLETED",
  "issues": [
    {
      "type": "SECURITY",
      "severity": "HIGH",
      "title": "Potential SQL Injection",
      "description": "User input concatenated in SQL query",
      "suggestion": "Use PreparedStatement with parameterized queries",
      "filePath": "src/main/java/Example.java",
      "lineNumber": 42
    }
  ]
}

🛠️ Development

Project Structure

CodeSage/
├── backend/                    # Spring Boot application
│   ├── src/main/java/com/codesage/
│   │   ├── controller/         # REST controllers
│   │   ├── service/            # Business logic (AI, GitHub)
│   │   ├── model/              # JPA entities
│   │   ├── repository/         # Data access
│   │   ├── queue/              # RabbitMQ consumers
│   │   └── exception/          # Error handling
│   └── Dockerfile
├── frontend/                   # React application
│   ├── src/
│   │   ├── services/           # API client
│   │   ├── App.jsx            # Main dashboard
│   │   └── App.css            # Styles
│   ├── Dockerfile
│   └── nginx.conf
├── docs/                       # Documentation
├── .github/workflows/          # CI/CD pipeline
└── docker-compose.yml          # Multi-service setup

Local Development

# Backend (without Docker)
cd backend
mvn spring-boot:run

# Frontend (without Docker)
cd frontend
npm install
npm run dev

Running Tests

# Backend tests
cd backend
mvn test

# Generate coverage report
mvn jacoco:report

🚧 Current Status

Production-Ready Features:

✅ Real AI integration (OpenAI GPT-4 + Claude fallback)
✅ GitHub App authentication with JWT
✅ Webhook processing with signature verification
✅ Asynchronous analysis with RabbitMQ
✅ PostgreSQL persistence with analytics
✅ Real-time dashboard with auto-refresh
✅ CI/CD pipeline with GitHub Actions
✅ Docker deployment configuration
✅ Comprehensive error handling
✅ Health checks and monitoring

Planned Enhancements:

🔄 Comprehensive test suite (unit + integration)
🔄 Live deployment (Railway/Render)
🔄 Custom review rules configuration
🔄 Multi-repository dashboard
🔄 Slack/Discord notifications

🔒 Security

Webhook Signature Verification: HMAC-SHA256 validation
JWT Authentication: Secure GitHub App integration
Environment Variables: All secrets externalized
Non-root Docker Containers: Security best practices
Input Validation: Spring Boot validation framework
CORS Configuration: Restricted origins in production

📈 Performance

Webhook Response: < 100ms (async processing)
AI Analysis: 5-15 seconds (depends on code size)
Dashboard Load: < 2 seconds
Database Queries: < 50ms (indexed)
Concurrent PRs: Scales horizontally with RabbitMQ

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

Java: Google Java Style Guide
JavaScript: ESLint with Airbnb config
Commits: Conventional Commits

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

Albon Idrizi

CodeSage

Install / Use

README