AI-Powered Repository Risk Intelligence Platform

Project Overview

An enterprise-grade platform that analyzes GitHub repositories to surface technical debt, security risk, and engineering health signals. It combines git history mining, static code analysis, security scanning, team intelligence, and lightweight AI insights into a single repository intelligence dashboard.

Problem Statement

Modern engineering teams struggle to understand the health of codebases across multiple dimensions. Existing tools often report one metric in isolation: complexity, security issues, or churn. This project solves that by synthesizing those signals into a unified risk and debt model, enabling teams to prioritize refactoring, reduce fragility, and make data-driven decisions.

Real-World Use Case

A delivery manager or engineering lead can connect a GitHub repository and run an automated analysis job. The platform then identifies:

• files with the highest technical debt and refactor priority,
• security hotspots and dependency vulnerabilities,
• contributors who own risky code,
• architecture-level coupling and instability,
• an overall engineering health score and portfolio comparison.

Target Users

• Engineering leads and architects
• Technical program managers
• DevOps and security analysts
• Developers preparing risk reports or technical debt remediation plans

Technology Stack

• Backend: Python 3.11, FastAPI, SQLModel, PostgreSQL, Redis, RQ
• Frontend: Next.js 14, React, Tailwind CSS
• Infrastructure: Docker Compose, GitHub cloning, Bandit, pip-audit, safety
• Optional AI: Google Gemini via google.generativeai

Architecture

The platform is organized as:

Browser / Frontend ↓ Next.js dashboard pages fetch metrics from ↓ FastAPI backend API (/api/v1/repos/...) ↓ PostgreSQL for persistence, Redis for job queuing and caching ↓ RQ worker executes backend/app/services/analysis_orchestrator.py ↓ Repository clone + analysis engines compute metrics ↓ Risk snapshots, file metrics, security issues, contributors, architecture metrics

Architecture

Browser
   │
   ▼
Next.js Frontend
   │
   ▼
FastAPI API
   ├── PostgreSQL
   │     └── SQLModel
   │        (backend/app/db/models.py)
   │
   ├── Redis
   │     └── RQ Worker
   │        (backend/app/workers/entrypoint.py)
   │
   └── RepoService
         │
         ▼
   Clone GitHub Repository
         │
         ▼
   Analysis Pipeline
      ├── Git Intelligence
      ├── Static File Intelligence
      ├── Security Scanning
      ├── Risk & Debt Scoring
      └── AI Insights

Key Files and Responsibilities

• backend/app/main.py: FastAPI app startup and CORS configuration
• backend/app/api/endpoints/repos.py: repository endpoints, dashboard payload assembly, analysis triggers, security and AI APIs
• backend/app/services/analysis_orchestrator.py: orchestrates full repository analysis and persisting results
• backend/app/db/models.py: database schema for repositories, jobs, files, metrics, security issues, risk snapshots
• backend/app/services/engines/technical_debt.py: computes technical debt score, breakdown, and hotspots
• backend/app/services/engines/risk_model.py: computes file-level and repo-level risk scores, health score, and fragility metrics
• frontend/src/app/dashboard/[repoId]/technical-debt/page.tsx: UI page for technical debt visualization
• frontend/src/lib/types.ts: shared frontend API response types

How to Run Locally

1. Create backend/.env with DATABASE_URL, REDIS_URL, SECRET_KEY.
2. Start the backend: cd backend && poetry install && poetry run uvicorn app.main:app --reload
3. Start the frontend: cd frontend && npm install && npm run dev
4. Open http://localhost:3000 and log in / connect a GitHub repo.

Recent Enhancements

• Added persisted technical debt breakdowns and file-level debt hotspots to repository risk snapshots.
• Extended the frontend dashboard with a Technical Debt page showing a donut chart and prioritized hotspot table.
• Included a backend schema migration for new debt_breakdown_json and debt_hotspots_json fields in risk_snapshots.
• Improved backend error reporting during analysis stage failures for faster debugging.

Development

• Backend: cd backend && poetry install
• Run locally: poetry run uvicorn app.main:app --reload

Copyright Notice

This repository is the intellectual property of the author.

This project may not be copied, reused, modified, submitted for academic evaluation, or presented as another person's work without explicit written permission.

Unauthorized academic use may be reported to the relevant institution.

By Visha, Bhakti and Purva!