"Explain My Code" Engine

An LLM-agnostic code explanation engine that provides deep insights into code quality, risks, and hidden assumptions.

Architecture

• Rust: Core AST parsing + performance-heavy analysis
• Python: Prompt orchestration / ML glue
• TypeScript: Web UI for code input and streaming explanations

Features

Instead of generic explanations, this engine answers:

• "What is the riskiest part of this code?"
• "Where would bugs hide?"
• "What assumption does this code silently make?"

Key Capabilities

• Language-agnostic AST normalization in Rust using tree-sitter
• Streaming explanations to the UI via Server-Sent Events
• Compare human vs static-analysis explanations side-by-side
• Multi-language support: JavaScript, TypeScript, Python, Rust, Java, Go

Project Structure

.
├── rust/              # AST parsing and analysis engine
│   ├── src/
│   │   ├── main.rs   # HTTP server and API endpoints
│   │   ├── ast.rs    # AST parsing and normalization
│   │   ├── analyzer.rs # Static analysis engine
│   │   └── language.rs # Language detection and tree-sitter integration
│   └── Cargo.toml
├── python/            # Prompt orchestration service
│   ├── main.py       # FastAPI server with LLM integration
│   ├── requirements.txt
│   └── .env.example
├── web/               # TypeScript web UI
│   ├── src/
│   │   ├── App.tsx   # Main application component
│   │   └── components/
│   │       ├── CodeEditor.tsx
│   │       ├── ExplanationPanel.tsx
│   │       ├── ComparisonView.tsx
│   │       └── LanguageSelector.tsx
│   └── package.json
├── start.sh          # Bash script to start all services (Linux/Mac)
├── start.ps1         # PowerShell script to start all services (Windows)
└── README.md

Getting Started

Prerequisites

• Rust (latest stable) - Install Rust
• Python 3.9+ - Install Python
• Node.js 18+ - Install Node.js
• An LLM API key (OpenAI or Anthropic)

Setup

1. Clone and navigate to the project:

   cd code-explainer

2. Configure Python environment:

   cd python
   pip install -r requirements.txt
   cp .env.example .env
   # Edit .env and add your API keys
   cd ..

3. Install web dependencies:

   cd web
   npm install
   cd ..

Running the Services

Option 1: Quick Start (Recommended)

Windows:

.\start.ps1

Linux/Mac:

chmod +x start.sh
./start.sh

Option 2: Manual Start

1. Rust Service (AST parsing) - Port 3001:

   cd rust
   cargo run

2. Python Service (Prompt orchestration) - Port 3002:

   cd python
   python main.py

3. Web UI - Port 3000:

   cd web
   npm run dev

Access the Application

Open your browser to: http://localhost:3000

API Endpoints

Rust Service (Port 3001)

• POST /api/analyze - Submit code for AST parsing and static analysis

  {
    "code": "function test() { return null; }",
    "language": "javascript"
  }

Python Service (Port 3002)

• POST /api/explain - Get LLM-powered explanations (streaming)

  {
    "code": "function test() { return null; }",
    "language": "javascript",
    "questions": ["What is the riskiest part of this code?"]
  }

• POST /api/compare - Compare static analysis vs LLM explanations

• GET /health - Health check endpoint

Configuration

Python Service (.env)

LLM_PROVIDER=openai  # or "anthropic"
OPENAI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
RUST_SERVICE_URL=http://localhost:3001

How It Works

1. User pastes code in the web UI
2. Rust service parses the code into a normalized AST and performs static analysis
3. Python service receives static analysis results and orchestrates LLM prompts
4. LLM generates explanations answering specific questions about risks, bugs, and assumptions
5. Results stream back to the UI in real-time
6. Comparison view shows side-by-side static analysis vs LLM insights

Supported Languages

• JavaScript
• TypeScript
• Python
• Rust
• Java
• Go

Development

Adding a New Language

1. Add tree-sitter language binding to rust/Cargo.toml
2. Add language variant to rust/src/language.rs
3. Update language selector in web/src/components/LanguageSelector.tsx

Extending Static Analysis

Edit rust/src/analyzer.rs to add new pattern detection rules.

Customizing LLM Prompts

Modify python/main.py build_prompt() function to customize how prompts are constructed.

Troubleshooting

• Rust service won't start: Make sure port 3001 is available
• Python service errors: Check that .env file exists and has valid API keys
• Web UI can't connect: Ensure both Rust and Python services are running
• Tree-sitter errors: Some languages may require additional setup - check tree-sitter documentation

License

MIT