🛡️ CodeSentinel

AI-powered code review platform that analyzes GitHub pull requests using LLMs to detect bugs, security vulnerabilities, and code quality issues — with line-level feedback.

Live Demo · API Docs · Architecture

The Problem

Manual code reviews are slow, inconsistent, and miss subtle bugs. Engineering teams waste hours on reviews that could be automated, and junior developers often lack senior-level feedback on their pull requests.

The Solution

CodeSentinel integrates directly with GitHub repositories via webhooks. When a pull request is opened or updated, CodeSentinel:

Receives the webhook event and extracts the diff
Queues the review job for async processing via Redis
Analyzes the code using LLM-powered pipelines (OpenAI GPT-4)
Posts line-level feedback directly on the PR as review comments

The result: instant, senior-engineer-quality code reviews on every pull request.

Key Features

🔍 Deep Static Analysis — LLM-powered analysis that goes beyond linting to catch logic errors, anti-patterns, and missed edge cases
🛡️ Security Scanning — Detects common vulnerabilities (SQL injection, XSS, hardcoded secrets, insecure dependencies)
📝 Line-Level Feedback — Comments are posted on specific lines in the PR diff, not as a wall of text
⚡ Async Processing — Webhook → Redis queue → worker pipeline. Reviews don't block your CI.
🔗 GitHub Integration — Native GitHub App with webhook receiver and PR comment API
📊 Dashboard — Next.js frontend to monitor reviews, configure repos, and view analytics
🏗️ Multi-File Analysis — Reviews entire PRs across multiple files, understanding cross-file dependencies

Architecture

┌─────────────────┐      ┌──────────────────┐      ┌──────────────┐
│   GitHub         │─────▶│  FastAPI          │─────▶│  Redis       │
│   Webhook Event  │      │  Webhook Receiver │      │  Job Queue   │
└─────────────────┘      └──────────────────┘      └──────┬───────┘
                                                          │
                                                          ▼
┌─────────────────┐      ┌──────────────────┐      ┌──────────────┐
│  GitHub PR       │◀─────│  Review           │◀─────│  LLM Worker  │
│  Line Comments   │      │  Publisher         │      │  (OpenAI)    │
└─────────────────┘      └──────────────────┘      └──────────────┘
                                │
                                ▼
                         ┌──────────────┐      ┌──────────────┐
                         │  PostgreSQL   │      │  Next.js     │
                         │  (Results DB) │◀────▶│  Dashboard   │
                         └──────────────┘      └──────────────┘

Data flow:

Developer opens a PR on a connected GitHub repository
GitHub sends a webhook event to the FastAPI receiver
The receiver validates the payload and enqueues a review job in Redis
A background worker picks up the job, fetches the PR diff, and sends it to the OpenAI API
The LLM returns structured findings (bugs, security issues, style suggestions) with line references
The publisher posts line-level review comments back to the GitHub PR via the GitHub API
All results are persisted in PostgreSQL and visible on the Next.js dashboard

Tech Stack

Layer	Technology	Why
Backend API	FastAPI (Python)	Async-native, auto-generated OpenAPI docs, type safety with Pydantic
Frontend	Next.js 14 (TypeScript)	App Router, Server Components, fast SSR
Database	PostgreSQL	Relational integrity for review data, user configs, repo settings
Queue	Redis	Lightweight async job processing, pub/sub for real-time updates
AI/LLM	OpenAI GPT-4 API	Best-in-class code understanding for review generation
Auth	GitHub OAuth	Seamless authentication via GitHub identity
Deployment	Vercel (frontend) · Docker (backend)	Zero-config frontend deploys, containerized backend

Project Structure

codesentinel-platform/
├── backend/
│   ├── app/
│   │   ├── api/              # Route handlers (webhooks, reviews, repos, auth)
│   │   │   ├── webhooks.py   # GitHub webhook receiver & validation
│   │   │   ├── reviews.py    # Review CRUD endpoints
│   │   │   └── repos.py      # Repository management
│   │   ├── core/             # Config, security, dependency injection
│   │   │   ├── config.py     # Environment variable management
│   │   │   └── security.py   # Webhook signature verification
│   │   ├── models/           # SQLAlchemy ORM models
│   │   ├── schemas/          # Pydantic request/response schemas
│   │   ├── services/         # Business logic layer
│   │   │   ├── review.py     # Review orchestration engine
│   │   │   ├── llm.py        # OpenAI API client & prompt engineering
│   │   │   └── github.py     # GitHub API client (PR comments, diff fetching)
│   │   ├── workers/          # Async queue consumers (Redis workers)
│   │   └── main.py           # FastAPI application entrypoint
│   ├── tests/                # pytest test suite
│   ├── Dockerfile
│   ├── requirements.txt
│   └── .env.example
├── frontend/
│   ├── src/
│   │   ├── app/              # Next.js App Router pages
│   │   ├── components/       # React components (ReviewCard, RepoList, etc.)
│   │   └── lib/              # API client, utilities, types
│   ├── package.json
│   └── next.config.js
├── docker-compose.yml        # Full stack: backend + frontend + postgres + redis
├── .github/
│   └── workflows/
│       └── ci.yml            # GitHub Actions CI pipeline
└── README.md

Getting Started

Prerequisites

Python 3.11+
Node.js 18+
PostgreSQL 15+
Redis 7+
OpenAI API key
GitHub App credentials (for webhook integration)

Installation

# Clone the repository
git clone https://github.com/hosama-adem/codesentinel-platform.git
cd codesentinel-platform

# Backend setup
cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# Frontend setup
cd ../frontend
npm install

Environment Variables

Create .env files in both backend/ and frontend/ directories. See .env.example for reference.

backend/.env

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/codesentinel

# Redis
REDIS_URL=redis://localhost:6379

# OpenAI
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4

# GitHub App
GITHUB_APP_ID=123456
GITHUB_PRIVATE_KEY_PATH=./private-key.pem
GITHUB_WEBHOOK_SECRET=whsec_...

# Server
HOST=0.0.0.0
PORT=8000
DEBUG=true

frontend/.env.local

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_GITHUB_CLIENT_ID=Iv1.abc123

Running Locally

# Option 1: Docker Compose (recommended)
docker-compose up --build

# Option 2: Manual
# Terminal 1 — Backend
cd backend && uvicorn app.main:app --reload --port 8000

# Terminal 2 — Worker
cd backend && python -m app.workers.review_worker

# Terminal 3 — Frontend
cd frontend && npm run dev

The application will be available at:

Frontend: http://localhost:3000
Backend API: http://localhost:8000
API Docs (Swagger): http://localhost:8000/docs

API Documentation

Interactive Swagger docs are available at /docs when the backend is running.

Core Endpoints

Method	Endpoint	Description
`POST`	`/api/v1/webhooks/github`	Receives GitHub webhook events (PR opened/updated)
`GET`	`/api/v1/reviews`	List all code reviews (paginated, filterable)
`GET`	`/api/v1/reviews/{id}`	Get detailed review with all findings
`GET`	`/api/v1/reviews/{id}/findings`	Get individual findings with line references
`POST`	`/api/v1/repos`	Register a repository for automated review
`GET`	`/api/v1/repos`	List connected repositories
`DELETE`	`/api/v1/repos/{id}`	Disconnect a repository
`GET`	`/api/v1/analytics`	Review statistics, trends, and metrics

Example Response

{
  "id": "rev_abc123",
  "repository": "hosama-adem/my-project",
  "pull_request": 42,
  "status": "completed",
  "findings": [
    {
      "type": "bug",
      "severity": "high",
      "file": "src/auth/handler.py",
      "line": 47,
      "message": "SQL query constructed with string concatenation. Use parameterized queries to prevent SQL injection.",
      "suggestion": "cursor.execute('SELECT * FROM users WHERE id = %s', (user_id,))"
    }
  ],
  "summary": {
    "total_findings": 5,
    "bugs": 2,
    "security": 1,
    "style": 2
  },
  "created_at": "2026-07-15T14:30:00Z"
}

Roadmap

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Write tests for your changes
Commit using conventional commits (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

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

Built by Hosama Adem

Navigation Menu

Repository files navigation

🛡️ CodeSentinel

The Problem

The Solution

Key Features

Architecture

Tech Stack

Project Structure

Getting Started

Prerequisites

Installation

Environment Variables

Running Locally

API Documentation

Core Endpoints

Example Response

Roadmap

Contributing

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
Screenshots		Screenshots
backend		backend
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AUDIT_AND_CHANGES.md		AUDIT_AND_CHANGES.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml

Latest commit

History

Folders and files

Repository files navigation

🛡️ CodeSentinel

The Problem

The Solution

Key Features

Architecture

Tech Stack

Project Structure

Getting Started

Prerequisites

Installation

Environment Variables

Running Locally

API Documentation

Core Endpoints

Example Response

Roadmap

Contributing

License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages