🚀 DevPilot AI

Understand any codebase — without ever running it.

DevPilot AI lets you import a public GitHub repository or ZIP file and instantly explore it through static analysis, semantic search, citation-backed AI chat, generated documentation, and structured code reviews — all grounded in verified file and line evidence.

---

📖 Table of Contents

• ✨ Features
• 🛠️ Tech Stack
• 🏗️ Architecture
• 📁 Project Structure
• ⚡ Quick Start
• 🔐 Environment Variables
• 🗄️ Database & Auth
• 🔒 Security Design
• 🧪 Testing
• 🚀 Deployment
• ⚠️ Known Limitations

---

✨ Features

#	Feature	Description
🔑	Authentication	Email/password login with optional Google OAuth via Supabase Auth
🗂️	Workspaces	User-owned workspaces with full CRUD — isolated and secured per user
📥	Safe Imports	Public GitHub repos (shallow clone) and ZIP files with background progress tracking
🔍	Static Analysis	Deterministic parsing of Python, Java, JavaScript, TypeScript, HTML, CSS, JSON, and Markdown
📊	Deep Metrics	Language, framework, dependency, symbol, route, test, and documentation metrics
🗺️	Repo Explorer	Browse source files with syntax preview and symbol navigation
🔎	Hybrid Search	Keyword, semantic, and reciprocal-rank fusion search powered by pgvector
💬	AI Chat	Repository chat with selected-file context and citation-verified responses
📝	Doc Generation	Auto-generate README, overview, architecture, module, and API documentation
🛡️	Code Reviews	Structured reviews grouped by severity with verified file and line references

---

🛠️ Tech Stack

Frontend

Technology	Role
Next.js 15 + React	App framework and routing
TypeScript	Type-safe development
Tailwind CSS + shadcn/ui	Styling and component system
TanStack Query	Server-state management and caching

Backend

Technology	Role
FastAPI	High-performance async API layer
SQLAlchemy + Alembic	ORM and schema migrations
Pydantic	Request/response validation

AI & Retrieval

Technology	Role
LangChain + LangGraph	Controlled AI orchestration workflows
FastEmbed BAAI/bge-small-en-v1.5	Local embeddings
Ollama / Groq	Local and hosted LLM inference
pgvector	Vector similarity search in PostgreSQL

Infrastructure

Technology	Role
Supabase	Auth (JWT) + PostgreSQL hosting
Vercel	Frontend hosting
Render	Backend hosting via render.yaml blueprint

---

🏗️ Architecture

┌─────────────────────────────────────┐
│      Next.js Browser Application    │
│  (Supabase Auth — JWT token only)   │
└────────────────┬────────────────────┘
                 │  Verified Supabase Access Token
                 ▼
┌─────────────────────────────────────┐
│     FastAPI — Auth & Ownership      │
│     (JWT verify + user scope)       │
└────┬──────────────┬─────────────────┘
     │              │              │
     ▼              ▼              ▼
Supabase       Safe Repo       Ollama (local)
PostgreSQL     Storage &       Groq (hosted)
+ pgvector     Analysis

Key principle: The browser touches Supabase only for authentication. Every application-data request goes through FastAPI, which verifies JWT signatures and enforces per-user workspace ownership before reading or writing any data.

---

📁 Project Structure

devpilot-ai/
├── frontend/          # Next.js 15 application (Vercel)
│   ├── app/           # App Router pages and layouts
│   ├── components/    # Reusable UI components
│   └── .env.example   # Frontend env template
├── backend/           # FastAPI application (Render)
│   ├── app/           # API routes, services, models
│   ├── migrations/    # Alembic migration scripts
│   └── .env.example   # Backend env template
├── render.yaml        # Render deployment blueprint
└── README.md

---

⚡ Quick Start

Prerequisites

• Python 3.11+
• Node.js 20+
• PostgreSQL with pgvector extension (or Supabase project)
• Ollama for local AI inference

---

1️⃣ Backend Setup

cd backend

# Create and activate virtual environment
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

# Configure environment
Copy-Item .env.example .env
# Edit .env with your Supabase and database credentials

# Run database migrations
.\.venv\Scripts\python.exe -m alembic upgrade head

# Start the API server
.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload --port 8000

API will be live at http://localhost:8000
Health checks: /api/v1/health/live · /api/v1/health/ready

---

2️⃣ Frontend Setup

cd frontend

npm install

# Configure environment
Copy-Item .env.example .env.local
# Edit .env.local with your Supabase and API URLs

npm run dev

App will be live at http://localhost:3000

---

3️⃣ Local AI (Ollama)

ollama pull llama3.1:8b
ollama serve

Set AI_PROVIDER=ollama in backend/.env for local inference.
Switch to AI_PROVIDER=groq with a GROQ_API_KEY for hosted inference.

---

🔐 Environment Variables

Frontend (frontend/.env.local)

Variable	Description
NEXT_PUBLIC_SUPABASE_URL	Your Supabase project URL
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY	Supabase anon/publishable key — never use service-role here
NEXT_PUBLIC_API_BASE_URL	FastAPI origin, without trailing /api/v1

Backend (backend/.env)

Variable	Description
DATABASE_URL	SQLAlchemy PostgreSQL connection string
SUPABASE_URL	JWT issuer and JWKS endpoint
FRONTEND_ORIGIN	Exact frontend origin for CORS
AI_PROVIDER	ollama (local) or groq (hosted)
GROQ_API_KEY	Groq API secret — backend only, never exposed to client
OLLAMA_BASE_URL	Ollama server URL (default: http://localhost:11434)
OLLAMA_MODEL	Model tag to use (e.g. llama3.1:8b)
WORKSPACE_STORAGE_ROOT	Directory where imported repos are stored
FASTEMBED_MODEL	Embedding model identifier
EMBEDDING_DIMENSION	Must match the chosen model's output dimension

📄 Full documentation for every variable is in backend/.env.example and frontend/.env.example.

---

🗄️ Database & Auth

Alembic manages all schema changes. The migration history creates:

• Profiles — linked to Supabase Auth users
• Workspaces — user-owned repository containers
• Import Jobs — background import progress tracking
• Repository Metadata — parsed analysis results
• Vector Chunks — embeddings for semantic search (pgvector)
• Conversations & Messages — chat history with citations
• Generated Documents — AI-produced documentation artifacts
• Code Reviews — structured severity-grouped review results

Current migration head: 20260730_10

Hosting tip: Use the Supabase Session Pooler URL for IPv4-compatible hosted database access. Set the production Site URL and /auth/callback redirect in Supabase Auth settings.

---

🔒 Security Design

DevPilot AI is designed with a zero-execution, evidence-grounded security model:

• 🚫 No code execution — imported code and its dependencies are never run
• 🔗 Safe Git imports — shallow, public-only, non-interactive; submodules and symlinks are rejected
• 📦 Safe ZIP imports — path traversal, symlinks, encrypted/nested archives, and oversized content are all rejected
• 🙈 Sensitive file exclusion — .env, key/certificate files, binaries, and archives are excluded from analysis and AI context
• ✅ Full JWT verification — FastAPI verifies Supabase JWT signatures, issuer, audience, expiry, and authenticated role on every request
• 👤 Per-user scoping — all workspace and artifact queries are filtered to the authenticated owner
• 🔏 Untrusted AI context — repository content is wrapped as untrusted evidence in prompts; model output is never trusted for file paths or line numbers
• 🔑 Secrets hygiene — secrets live only in ignored local files or hosting dashboards, never in source code

---

🧪 Testing

Backend

cd backend

# Linting
.\.venv\Scripts\python.exe -m ruff check app tests --no-cache

# Type checking
.\.venv\Scripts\python.exe -m mypy app --cache-dir nul

# Unit & integration tests
.\.venv\Scripts\python.exe -m pytest -q

Frontend

cd frontend

npm run lint
npm run typecheck -- --incremental false
npm test -- --run
npm run build

Coverage includes: auth failures, ownership enforcement, safe imports, parsers, file containment, pgvector retrieval, chat citations, document generation, code reviews, and frontend user flows.

---

🚀 Deployment

🌐 Live Deployment

Service	URL
Frontend (Vercel)	https://devpilot-ai-gamma.vercel.app
Backend (Render)	https://devpilot-ai-owr2.onrender.com
API Docs	https://devpilot-ai-owr2.onrender.com/docs

Frontend → Vercel

1. Import frontend/ as a Next.js project in Vercel
2. Add all NEXT_PUBLIC_* environment variables in the Vercel dashboard
3. Set NEXT_PUBLIC_API_BASE_URL to your Render backend URL

Backend → Render

1. Connect this repository to Render and select the Blueprint option using render.yaml
2. Add all backend environment variables in the Render dashboard
3. Set FRONTEND_ORIGIN to your production Vercel URL
4. Configure the same origin in Supabase Auth → URL Configuration

---

⚠️ Known Limitations

• Only public GitHub repositories and ZIP files are supported
• Imported repositories are intentionally never built or executed
• Google OAuth requires manual setup in both Google Cloud Console and Supabase Auth
• Groq requires a user-provided API key; Ollama is the free local default
• Render's free tier filesystem is ephemeral — hosted source files may disappear after sleep or redeploy; local use is more reliable
• The built-in Markdown viewer supports common formatting from the documentation workflow, not every Markdown extension
• This is a student demonstration project, not a production-grade multi-tenant service

---

Built with ❤️ as a final-year project · GitHub · Live Demo