VibeDebugger 🚀

A powerful AI-powered codebase exploration and debugging tool that helps developers understand, analyze, and interact with their repositories through semantic search and intelligent chat assistance.

✨ Features

🔍 Semantic Code Search

Vector-based similarity search using OpenAI embeddings
Find code by meaning, not just keywords
Precise file location and line number results
Support for 30+ programming languages

🤖 AI-Powered Chat Assistant

Context-aware conversations about your codebase
Code explanation and debugging suggestions
Architecture insights and refactoring recommendations
Integrated with repository knowledge

🎤 Voice Assistant Integration

VAPI-powered voice interactions
Hands-free codebase exploration
Voice-activated feature introductions
Real-time conversation capabilities

📊 Repository Analytics

Comprehensive repository analytics showing commit history, file changes, and contributor data visualization. The dashboard displays detailed insights into code activity patterns, contribution metrics, and repository evolution over time.

AI-generated code detection analysis
Commit timeline visualization with contributor insights
Repository health and complexity metrics
Interactive charts and statistics

🔄 Smart Repository Management

GitHub OAuth integration
Automated code indexing with progress tracking
Support for both public and private repositories
Optimized handling of large repositories (500+ files)

🎨 Modern UI/UX

Clean, responsive dashboard interface
Syntax highlighting for code blocks
Clickable file paths with GitHub integration
Real-time status updates and notifications

🛠️ Tech Stack

Frontend

Next.js 15.5 - React framework with App Router
TypeScript - Type-safe development
Tailwind CSS 4.0 - Utility-first styling
Lucide React - Beautiful icons
React Markdown - Rich text rendering

Backend

NextAuth.js 5.0 - Authentication with GitHub OAuth
Prisma - Database ORM
Neon DB - Serverless PostgreSQL database platform
PostgreSQL - Primary database (via Neon DB)
Qdrant - Vector database for semantic search

AI & ML

OpenAI GPT-4 - Chat completions and analysis
OpenAI text-embedding-ada-002 - Text embeddings
VAPI - Voice assistant integration
Custom AI Detection - Code analysis algorithms

Infrastructure

Docker - Containerized services
GitHub API - Repository data fetching
Octokit - GitHub API client

🚀 Quick Start

Prerequisites

Node.js 18+ and npm
Neon DB account (serverless PostgreSQL)
Docker and Docker Compose (for Qdrant)
GitHub OAuth App credentials
OpenAI API key
VAPI account (optional, for voice features)

Installation

Clone the repository

git clone https://github.com/your-username/vibe-debugger.git
cd vibe-debugger

Install dependencies
```
npm install
```

Set up environment variables Create a .env.local file:

# NextAuth.js
NEXTAUTH_SECRET=your-secret-key
NEXTAUTH_URL=http://localhost:3000

# GitHub OAuth
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# Database (Neon DB Connection String)
DATABASE_URL=postgresql://username:password@ep-example-123.us-east-1.aws.neon.tech/vibe_debugger?sslmode=require

# OpenAI
OPENAI_API_KEY=sk-your-openai-api-key

# Qdrant Vector Database
QDRANT_URL=http://localhost:6333

# VAPI Voice Assistant (optional)
NEXT_PUBLIC_VAPI_PUBLIC_KEY=your-vapi-public-key

Start Qdrant with Docker

Qdrant vector database running successfully on Docker, showing the container status, port mapping, and storage configuration. This setup provides the vector search capabilities essential for semantic code search.
```
docker run -p 6333:6333 -v $(pwd)/qdrant_storage:/qdrant/storage qdrant/qdrant
```

Set up the database

# Deploy migrations to Neon DB
npx prisma migrate deploy
npx prisma generate

Start the development server
```
npm run dev
```
Open your browser Navigate to http://localhost:3000

📖 Usage Guide

Getting Started

Sign in with GitHub - Authenticate using your GitHub account
Add a Repository - Click "Add Repository" and enter a GitHub URL
Index the Repository - Wait for the AI to process and index your code
Start Exploring - Use chat or search to interact with your codebase

Key Workflows

🔍 Semantic Search

"Where is the user authentication logic?"
"Find functions that handle file uploads"
"Show me error handling patterns"

💬 AI Chat Examples

"Explain how this authentication system works"
"What are the main security vulnerabilities?"
"How can I optimize the database queries?"
"Suggest refactoring opportunities"

🎤 Voice Commands

"Tell me about this repository"
"What are the main features?"
"How do I get started with development?"

🏗️ Architecture

System Overview

High-level system architecture showing the interaction between frontend components, backend services, and external APIs. The diagram illustrates how VibeDebugger integrates Next.js, PostgreSQL, Qdrant vector database, and various AI services.

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Next.js App   │◄──►│   PostgreSQL    │    │     Qdrant      │
│   (Frontend)    │    │   (Metadata)    │    │  (Embeddings)   │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   GitHub API    │    │   OpenAI API    │    │   VAPI Service  │
│  (Repository)   │    │ (Embeddings/Chat)│    │    (Voice)     │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Data Flow

Detailed sequence diagram showing the complete workflow from repository indexing to AI-powered code search and chat interactions. This diagram demonstrates how user queries are processed through vector embeddings and semantic search to provide intelligent responses.

Repository Ingestion: GitHub API → Code Parsing → Chunking
Vector Generation: Code Chunks → OpenAI Embeddings → Qdrant Storage
Semantic Search: Query → Embedding → Vector Search → Results
AI Chat: Context + Query → GPT-4 → Response + Code References

Key Components

/src/lib/code-indexer-optimized.ts - Smart repository indexing
/src/lib/ai-detector.ts - AI-generated code analysis
/src/components/chat/ - Chat interface and message handling
/src/components/voice-assistant/ - Voice interaction components
/src/app/api/ - Backend API routes

🎯 AI Detection Features

VibeDebugger includes advanced AI detection capabilities:

Detection Methods

Perplexity Analysis - Statistical language patterns
Syntax Perfection Scoring - Code consistency metrics
Comment Quality Assessment - Documentation patterns
Structural Analysis - Code organization patterns
Pattern Recognition - Common AI-generated signatures

Accuracy Disclaimer

Results are based on 2024 AI detection research and are probabilistic, not definitive. Use as guidance rather than absolute determination.

🔧 Configuration

Environment Variables

Variable	Description	Required	Default
`NEXTAUTH_SECRET`	NextAuth.js encryption key	✅	-
`NEXTAUTH_URL`	Application base URL	✅	-
`GITHUB_CLIENT_ID`	GitHub OAuth app ID	✅	-
`GITHUB_CLIENT_SECRET`	GitHub OAuth app secret	✅	-
`DATABASE_URL`	Neon DB PostgreSQL connection string	✅	-
`OPENAI_API_KEY`	OpenAI API key	✅	-
`QDRANT_URL`	Qdrant vector database URL	✅	`http://localhost:6333`
`NEXT_PUBLIC_VAPI_PUBLIC_KEY`	VAPI voice service key	❌	-

GitHub OAuth Setup

Go to GitHub → Settings → Developer settings → OAuth Apps
Create a new OAuth App with:
- Homepage URL: http://localhost:3000
- Authorization callback URL: http://localhost:3000/api/auth/callback/github
Copy the Client ID and Client Secret to your .env.local

OpenAI API Setup

Visit OpenAI Platform
Create an API key with access to:
- text-embedding-ada-002 model
- gpt-4 model (or gpt-3.5-turbo as fallback)
Add the API key to your environment variables

Neon DB Setup

Neon DB dashboard showing database statistics, contributor data analytics, and performance metrics. The dashboard provides real-time insights into database usage, query performance, and contributor activity patterns.

Create a Neon DB account
Create a new project and database
Copy the connection string from your Neon dashboard
The connection string format: postgresql://username:password@ep-xxx-xxx.region.aws.neon.tech/database_name?sslmode=require
Add the connection string to your .env.local as DATABASE_URL

Neon DB Benefits:

Serverless PostgreSQL with automatic scaling
Built-in connection pooling
Branch-based development workflows
No database maintenance required

📊 Performance & Limits

Repository Size Handling

Small repos (< 100 files): Full indexing
Medium repos (100-800 files): Smart filtering
Large repos (> 800 files): Priority-based selection (500 files max)

Rate Limiting

GitHub API: 5,000 requests/hour (authenticated)
OpenAI API: 3 requests/second for embeddings
Batch Processing: 3 files per batch with 1s delays

Storage Requirements

Neon DB: ~1KB per repository metadata (serverless PostgreSQL)
Qdrant: ~6KB per code chunk (1536-dimension vectors)
Estimated: 50MB vector storage per 10,000 lines of code

🚀 Deployment

Production Environment

Database Setup
```
# Deploy migrations to production Neon DB
npx prisma migrate deploy
```
Production Neon DB Configuration:
- Use production branch in Neon console
- Enable connection pooling for better performance
- Set up database branching for staging environments
- Configure automatic backups and point-in-time recovery

Qdrant Deployment

# Using Docker in production
docker run -d --name qdrant-prod \
  -p 6333:6333 \
  -v /path/to/storage:/qdrant/storage \
  qdrant/qdrant

Build and Start
```
npm run build
npm start
```

Docker Deployment

# Dockerfile example
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

🧪 Testing

Run Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
npm test -- --testPathPattern=ai-detector

Manual Testing Checklist

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests (npm test)
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

TypeScript: Strict type checking enabled
ESLint: Extended Next.js configuration
Prettier: Automated code formatting
Conventional Commits: Standardized commit messages

📝 API Reference

Repository Management

POST /api/repositories - Add new repository
GET /api/repositories - List user repositories
POST /api/repositories/[id]/index - Start indexing
POST /api/repositories/[id]/cancel-index - Cancel indexing
DELETE /api/repositories/[id]/delete - Delete repository

Search & Chat

POST /api/search - Semantic code search
POST /api/chat - AI chat completions
GET /api/repositories/[id]/commits - Repository commits

🐛 Troubleshooting

Common Issues

1. "Qdrant connection failed"

# Check if Qdrant is running
docker ps | grep qdrant

# Start Qdrant if not running
docker run -p 6333:6333 qdrant/qdrant

2. "OpenAI API rate limit exceeded"

Check your OpenAI account usage and billing
Reduce batch sizes in indexing configuration
Implement request queuing for large repositories

3. "GitHub OAuth callback error"

Verify callback URL matches OAuth app configuration
Check NEXTAUTH_URL environment variable
Ensure GitHub OAuth app is active

4. "Database migration failed"

# For development (local database reset)
npx prisma migrate reset
npx prisma migrate dev

# For production (Neon DB)
npx prisma migrate deploy

5. "Neon DB connection issues"

Verify your connection string includes ?sslmode=require
Check if your Neon project is active (not suspended)
Ensure your IP is whitelisted if using IP restrictions
Try connecting directly from Neon console to test connectivity

Debug Mode

Enable detailed logging:

NODE_ENV=development
DEBUG=true

📄 License

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

🙏 Acknowledgments

OpenAI for GPT-4 and embedding models
Qdrant for vector database technology
GitHub for repository API and OAuth
VAPI for voice assistant capabilities
Vercel for Next.js framework and hosting platform

📧 Support

Documentation: GitHub Wiki
Issues: GitHub Issues
Discussions: GitHub Discussions
Email: support@vibedebuger.com

Built with ❤️ by developers, for developers

Making code exploration intelligent and intuitive

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
imgs		imgs
prisma		prisma
public		public
src		src
.gitignore		.gitignore
README.md		README.md
VOICE_ASSISTANT_SETUP.md		VOICE_ASSISTANT_SETUP.md
docker-compose.yml		docker-compose.yml
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

KikiSpace/vibe_debugger

Folders and files

Latest commit

History

Repository files navigation