NeuroDebug

Neuro-Symbolic AI Code Debugger

A production-grade AI-powered debugging platform that combines static AST analysis with dynamic execution verification

Live Demo • Documentation • API Docs • Architecture • Roadmap • Report Bug • Request Feature

---

🚀 Product Overview

NeuroDebug solves the fundamental problem of automated code debugging by combining the reliability of static analysis with the intelligence of large language models. Traditional debuggers either rely on static rule-based systems that miss complex errors, or purely LLM-based approaches that can hallucinate fixes without verification.

Why Existing Debuggers Are Insufficient

• Static Analysis Tools: Fast but limited to predefined patterns, miss context-dependent bugs
• Pure LLM Solutions: Generate plausible but unverified fixes that may introduce new issues
• Traditional Debuggers: Require manual execution and breakpoint management, not automated

Why NeuroDebug Exists

NeuroDebug introduces a neuro-symbolic approach that merges deterministic AST analysis with neural LLM reasoning, then validates every candidate patch through actual execution. This hybrid architecture ensures:

• Deterministic Detection: 13 static rules catch common Python errors with zero false positives
• Contextual Understanding: LLM analysis provides nuanced explanations for complex issues
• Verified Fixes: Every candidate patch is executed and tested before presentation
• Structured Evidence: Complete execution reports with stdout, stderr, and test results

---

✨ Key Features

Feature	Description
Neuro-Symbolic Analysis	Combines AST parsing with 13 deterministic rules for static error detection
Candidate Patch Generation	LLM-powered fix generation with syntax validation and diff visualization
Execution Verification	Isolated subprocess execution validates patches before presentation
AST Rule Engine	13 static rules (R001-R013) covering syntax, undefined variables, anti-patterns
Unified Diff Viewer	Monaco Editor integration with syntax highlighting and side-by-side diff
Secure Verification Pipeline	Timeout-protected execution with structured evidence collection
Structured Logging	Request-scoped logging with pipeline stage timing and error tracking
Modern UI	React 19 with responsive design, dark/light themes, and smooth animations
JWT Authentication	Secure email/password authentication with access and refresh tokens
Session Management	Secure cookie-based session persistence with configurable expiration
Workspace Management	Projects CRUD operations with archiving and soft delete support
Debug History	Full session persistence with search, filters, restore, compare, and export
Redis Caching	Deterministic cache keys with TTL and graceful fallback for performance
Performance Metrics	Per-stage timing (AST, rule, LLM, verification, database) for analytics
Analytics Dashboard	Professional charts showing usage, success rates, and performance trends
Security Enhancements	CSRF protection, input validation, session expiration, and rate limiting
Command Palette	Keyboard shortcuts (Cmd+K) for quick navigation and actions
Skeleton Loading	Beautiful loading states with animated skeletons for better UX
SaaS Foundation	PostgreSQL persistence, subscription tiers, usage limiting, analytics
Anonymous Access	Guest users can debug without account creation
Subscription Tiers	Configurable Guest, Free, Pro, and Enterprise plans

---

🏗️ System Architecture

Overall Architecture

graph TD
    A[User Browser] --> B[React Frontend]
    B --> C[FastAPI Backend]
    C --> D[Session Manager]
    C --> E[Usage Engine]
    C --> F[Debug Service]
    F --> G[AST Parser]
    F --> H[Rule Engine]
    F --> I[Groq LLM Client]
    F --> J[Patch Generator]
    F --> K[Verification Engine]
    F --> L[Execution Layer]
    F --> M[Test Runner]
    F --> N[Diff Service]
    C --> O[PostgreSQL]
    C --> P[Redis Cache]
    C --> Q[Repository Layer]
    C --> R[Service Layer]
    C --> S[Auth Service]
    C --> T[Workspace Service]
    C --> U[History Service]
    C --> V[Analytics Service]
    C --> W[Performance Service]
    
    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#e8f5e9
    style D fill:#f3e5f5
    style E fill:#f3e5f5
    style F fill:#f3e5f5
    style G fill:#f3e5f5
    style H fill:#f3e5f5
    style I fill:#f3e5f5
    style J fill:#f3e5f5
    style K fill:#f3e5f5
    style L fill:#f3e5f5
    style M fill:#f3e5f5
    style N fill:#f3e5f5
    style O fill:#fce4ec
    style P fill:#ffeb3b
    style Q fill:#d1c4e9
    style R fill:#c8e6c9
    style S fill:#b2dfdb
    style T fill:#b2dfdb
    style U fill:#b2dfdb
    style V fill:#b2dfdb
    style W fill:#b2dfdb

Loading

Database Schema

erDiagram
    subscription_plans ||--o{ subscription_limits : "has"
    subscription_plans ||--o{ users : "subscribes to"
    users ||--o{ projects : "owns"
    users ||--o{ usage_logs : "generates"
    users ||--o{ debug_sessions : "creates"
    projects ||--o{ debug_sessions : "contains"
    debug_sessions ||--o{ candidate_patches : "generates"
    debug_sessions ||--o{ verification_reports : "has"
    candidate_patches ||--o{ verification_reports : "verified by"

    subscription_plans {
        uuid id PK
        string tier
        integer daily_request_limit
        jsonb features
        boolean is_active
    }

    users {
        uuid id PK
        string email UK
        string password_hash
        boolean email_verified
        string display_name
        uuid subscription_plan_id FK
        timestamp last_login_at
    }

    projects {
        uuid id PK
        uuid user_id FK
        string name
        text description
        boolean is_archived
        timestamp last_used_at
    }

    debug_sessions {
        uuid id PK
        uuid user_id FK
        uuid project_id FK
        string session_id
        text code
        string error_type
        jsonb ast_analysis
        jsonB rule_violations
        text llm_analysis
        text candidate_patch
        jsonb verification_report
        float pipeline_duration_ms
        float confidence_score
    }

    usage_logs {
        uuid id PK
        uuid user_id FK
        string session_id
        timestamp request_timestamp
        string subscription_tier
    }

Loading

Request Lifecycle

sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant Session
    participant Usage
    participant Pipeline
    participant LLM
    participant DB

    User->>Frontend: Submit Code
    Frontend->>API: POST /debug
    API->>Session: Get/Create Session
    Session->>DB: Query Session
    DB-->>Session: Session Data
    Session-->>API: Session ID + Tier
    API->>Usage: Check Rate Limit
    Usage->>DB: Query Daily Usage
    DB-->>Usage: Current Usage
    Usage-->>API: Limit Check
    API->>Pipeline: Execute Debug
    Pipeline->>Pipeline: AST Analysis
    Pipeline->>Pipeline: Rule Engine
    Pipeline->>LLM: Generate Analysis
    LLM-->>Pipeline: LLM Response
    Pipeline->>LLM: Generate Patch
    LLM-->>Pipeline: Candidate Patch
    Pipeline->>Pipeline: Verify Patch
    Pipeline-->>API: Debug Result
    API->>Usage: Record Usage
    Usage->>DB: Insert Usage Log
    API-->>Frontend: Response + Usage Info
    Frontend-->>User: Display Results

Loading

Authentication Flow

sequenceDiagram
    participant User
    participant Frontend
    participant AuthAPI
    participant JWTService
    participant DB
    participant Redis

    User->>Frontend: Register (email, password)
    Frontend->>AuthAPI: POST /auth/register
    AuthAPI->>DB: Check if email exists
    DB-->>AuthAPI: Email not found
    AuthAPI->>AuthAPI: Hash password (bcrypt)
    AuthAPI->>DB: Create user with password_hash
    DB-->>AuthAPI: User created
    AuthAPI->>JWTService: Generate access token
    JWTService-->>AuthAPI: Access token
    AuthAPI->>JWTService: Generate refresh token
    JWTService-->>AuthAPI: Refresh token
    AuthAPI->>Redis: Store refresh token
    AuthAPI-->>Frontend: Tokens + user data
    Frontend->>Frontend: Store tokens in secure cookies
    Frontend-->>User: Redirect to dashboard

    Note over User,Redis: Login Flow

    User->>Frontend: Login (email, password)
    Frontend->>AuthAPI: POST /auth/login
    AuthAPI->>DB: Find user by email
    DB-->>AuthAPI: User data
    AuthAPI->>AuthAPI: Verify password hash
    AuthAPI->>JWTService: Generate access token
    JWTService-->>AuthAPI: Access token
    AuthAPI->>JWTService: Generate refresh token
    JWTService-->>AuthAPI: Refresh token
    AuthAPI->>DB: Update last_login_at
    AuthAPI->>Redis: Store refresh token
    AuthAPI-->>Frontend: Tokens + user data
    Frontend->>Frontend: Store tokens in secure cookies
    Frontend-->>User: Redirect to dashboard

    Note over User,Redis: Token Refresh Flow

    Frontend->>AuthAPI: POST /auth/refresh (refresh token)
    AuthAPI->>Redis: Validate refresh token
    Redis-->>AuthAPI: Token valid
    AuthAPI->>JWTService: Generate new access token
    JWTService-->>AuthAPI: New access token
    AuthAPI-->>Frontend: New access token
    Frontend->>Frontend: Update stored token

    Note over User,Redis: Protected API Request

    Frontend->>AuthAPI: GET /protected (access token)
    AuthAPI->>JWTService: Validate access token
    JWTService-->>AuthAPI: Token valid
    AuthAPI->>DB: Fetch user data
    DB-->>AuthAPI: User data
    AuthAPI-->>Frontend: Protected data

Loading

---

📦 Installation

Prerequisites

• Docker and Docker Compose
• Python 3.11+
• Node.js 20+
• PostgreSQL 16+ (for local development without Docker)

Quick Start with Docker

# Clone the repository
git clone https://github.com/joshi-chinmay-016/NeuroDebug.git
cd NeuroDebug

# Start all services
docker-compose up -d

# Access the application
# Frontend: http://localhost:3000
# Backend API: http://localhost:8000
# API Docs: http://localhost:8000/docs

Local Development

Backend Setup

cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Run database migrations
alembic upgrade head

# Seed database with subscription plans
python scripts/seed_database.py

# Start development server
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Frontend Setup

cd frontend

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Start development server
npm run dev

---

🔧 Configuration

Backend Environment Variables

# Database
DATABASE_URL=postgresql+asyncpg://neurodebug:neurodebug@localhost:5432/neurodebug
DATABASE_ECHO=false
DATABASE_POOL_SIZE=5
DATABASE_MAX_OVERFLOW=10

# Groq API
GROQ_API_KEY=your_groq_api_key_here
GROQ_MODEL=llama-3.1-8b-instant

# Session
SESSION_EXPIRY_HOURS=24

# Usage Limits
DEFAULT_GUEST_LIMIT=3
DEFAULT_FREE_LIMIT=5
DEFAULT_PRO_LIMIT=20

# Logging
LOG_LEVEL=INFO

Frontend Environment Variables

# API Configuration
VITE_API_URL=http://localhost:8000

# Firebase Configuration (optional)
VITE_FIREBASE_API_KEY=your_api_key_here
VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your_project_id

---

💡 Usage

Basic Debugging

import requests

API_URL = "http://localhost:8000"

response = requests.post(
    f"{API_URL}/debug",
    json={
        "code": "def example():\n    return undefined_var",
        "api_key": "gsk_..."  # Optional
    }
)

result = response.json()
print(result["explanation"])
print(result["candidate_patch"]["patched_code"])

With Verification

response = requests.post(
    f"{API_URL}/verify",
    json={
        "original_code": "def example():\n    return undefined_var",
        "patched_code": "def example():\n    return None",
        "test_code": "def test_example():\n    assert example() is None"
    }
)

result = response.json()
print(result["verification_status"])
print(result["evidence"]["execution_comparison"])

---

🧪 Testing

Backend Tests

cd backend

# Run all tests
pytest

# Run with coverage
pytest --cov=.

# Run specific test file
pytest tests/test_debug_service.py

Frontend Tests

cd frontend

# Run linting
npm run lint

# Run tests (when implemented)
npm test

---

📊 Subscription Tiers

Feature	Guest	Free	Pro	Enterprise
Daily Requests	3	5	20+	Unlimited
AST Analysis	✅	✅	✅	✅
Rule Engine	✅	✅	✅	✅
LLM Analysis	❌	✅	✅	✅
Patch Generation	❌	✅	✅	✅
Verification	❌	✅	✅	✅
Projects	0	3	Unlimited	Unlimited
History	❌	✅	✅	✅
API Access	❌	❌	✅	✅
Priority Processing	❌	❌	✅	✅
Team Features	❌	❌	❌	✅

---

📁 Project Structure

NeuroDebug/
├── backend/
│   ├── alembic/              # Database migrations
│   ├── database/             # Database models and configuration
│   │   ├── base.py          # Base classes and mixins
│   │   ├── models.py        # SQLAlchemy models
│   │   └── __init__.py      # Database session management
│   ├── repositories/         # Repository pattern implementation
│   │   ├── base.py          # Base repository
│   │   ├── user_repository.py
│   │   ├── project_repository.py
│   │   └── ...
│   ├── routes/               # API route handlers
│   │   └── debug.py
│   ├── services/             # Business logic layer
│   │   ├── debug_service.py
│   │   ├── session_service.py
│   │   ├── usage_limit_service.py
│   │   └── ...
│   ├── analysis/             # AST analysis
│   ├── llm/                  # LLM integration
│   ├── models/               # Pydantic models
│   ├── tests/                # Backend tests
│   ├── scripts/              # Utility scripts
│   ├── main.py               # Application entry point
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── components/       # React components
│   │   │   ├── Dashboard.jsx
│   │   │   ├── Projects.jsx
│   │   │   ├── History.jsx
│   │   │   ├── Analytics.jsx
│   │   │   ├── Pricing.jsx
│   │   │   ├── Settings.jsx
│   │   │   └── ...
│   │   ├── contexts/         # React contexts
│   │   ├── lib/              # Utility functions
│   │   ├── App.jsx           # Main application
│   │   └── main.jsx          # Entry point
│   ├── public/               # Static assets
│   ├── package.json
│   ├── tailwind.config.js
│   └── vite.config.js
├── docs/                     # Documentation
│   ├── architecture.md
│   ├── database.md
│   ├── deployment.md
│   ├── api.md
│   └── roadmap.md
├── .github/
│   └── workflows/
│       └── ci.yml            # CI/CD pipeline
├── docker-compose.yml        # Docker orchestration
└── README.md

---

🛠️ Development Workflow

Git Workflow

1. Create a feature branch from main
2. Implement your changes
3. Run tests and linting
4. Commit with conventional commits
5. Push and create a pull request
6. Ensure CI passes
7. Request review and merge

Conventional Commits

feat: add user authentication
fix: resolve session management bug
docs: update API documentation
style: format code with black
refactor: improve repository pattern
test: add integration tests
chore: update dependencies

---

🤝 Contributing

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

Areas for Contribution

• Additional language support
• Custom rule templates
• UI component improvements
• Documentation enhancements
• Bug fixes
• Performance improvements
• Test coverage

---

📝 License

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

---

🙏 Acknowledgments

• Groq for providing the LLM API
• FastAPI for the excellent web framework
• React for the amazing UI library
• PostgreSQL for the robust database
• All contributors and early adopters

---

📞 Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@neurodebug.com

---

🗺️ Roadmap

Check our Roadmap for upcoming features and planned improvements.

Upcoming Features

• Firebase Auth integration
• Real-time analytics dashboard
• Team collaboration features
• API access and webhooks
• Mobile applications
• Multi-language support

---

Built with ❤️ for developers who demand excellence

⭐ Star us on GitHub • 🐦 Follow us on Twitter • 💬 Join our Discord