DiffVault

A diff tool that goes beyond traditional comparison.

DiffVault combines multiple diff algorithms with AI-powered explanations to deliver the most comprehensive code analysis experience available. Better than GitHub diff. Better than PyCharm diff.

---

Quick Start

# Clone and run in 2 commands
git clone https://github.com/your-org/diffvault.git
cd diffvault
cp .env.example .env
docker compose up --build

Open http://localhost:8000 and start comparing code instantly.

---

Why DiffVault?

Traditional diff tools show you what changed. DiffVault shows you why it matters.

Multi-Level Analysis Engine

DiffVault runs 4 sophisticated diff algorithms simultaneously:

Level	Algorithm	What it detects	Technology
1	Myers Line Diff	Line additions, deletions, modifications	difflib (same as Git)
2	Token Inline Diff	Character-level highlights within lines	diff-match-patch
3	AST Structural Diff	Code moves, renames, refactors	GumTree + Tree-sitter
4	AI Explanation	Plain-English context and impact	OpenAI GPT-4 / Anthropic Claude

Intelligent Change Classification

DiffVault automatically categorizes every change:

• 🟢 ADDED - New lines of code
• 🔴 DELETED - Removed lines of code
• 🟡 MODIFIED - Changed lines with inline highlights
• 🔵 RENAMED - Variables/functions that were renamed
• 🟣 MOVED - Code blocks that moved to new locations
• 🟠 REFORMATTED - Pure formatting changes (spacing, braces)
• ⚪ UNCHANGED - Context lines for reference

---

Features

Beautiful Interface

• Split View - Side-by-side comparison like IDEs
• Unified View - Traditional git-style diff layout
• Syntax Highlighting - Language-aware color coding
• Inline Highlights - Red/green character-level changes within lines
• Smooth Scrolling - Perfectly synchronized panes with keyboard navigation

Professional Tools

• Keyboard Shortcuts - Ctrl+Enter to run diff, Alt+↑/↓ to navigate changes
• Change Navigation - Jump between changes with highlighting
• Code Folding - Collapse unchanged regions for focus
• Patch Export - Copy .patch files for version control
• File Type Detection - Auto-detects 20+ programming languages

AI-Powered Insights (Optional)

Add your API key to .env to enable AI explanations:

# Choose your provider
OPENAI_API_KEY=sk-...
# or
ANTHROPIC_API_KEY=sk-ant-...

Get plain-English explanations like:

"Renamed calculate_total to compute_sum and updated all 3 references. This appears to be a naming consistency improvement across the payment module."

---

Architecture

Backend Engine (Python)

engine/
├── pipeline.py     # Main orchestrator - single entry point
├── algorithms.py   # Core diff algorithms (Myers, GumTree, inline)
├── lexer.py        # Language detection and tokenization  
├── parser.py       # AST parsing with Tree-sitter
├── classifier.py   # Change type classification
├── explainer.py    # AI explanation layer
└── schema.py       # Type definitions and data models

Frontend UI (Vanilla JS)

ui/static/
├── js/main.js      # 1200+ lines of sophisticated diff rendering
├── css/main.css    # Professional VS Code-inspired styling
└── templates/      # Clean, semantic HTML structure

No frameworks required - Pure, performant web standards.

---

Supported Languages

DiffVault automatically detects and provides syntax-aware diffing for:

Category	Languages
Popular	Python, JavaScript, TypeScript, Java, Go, Rust
Systems	C, C++, C#
Web	HTML, CSS, SCSS, JSON, XML
Data	SQL, YAML, TOML
Scripts	Shell, PowerShell, Dockerfile
Config	Markdown, INI, Properties
[TODO]	More languages added via Tree-sitter grammars

---

Development

Local Development Setup

# Clone the repository
git clone https://github.com/your-org/diffvault.git
cd diffvault

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

# Install dependencies
pip install -r requirements.txt

# Setup environment
cp .env.example .env
# Edit .env with your settings

# Run development server
python manage.py runserver

Project Structure

diffvault/
├── engine/           # Core diff engine (reusable library)
├── ui/              # Django web interface
├── diffvault/        # Django project settings
├── staticfiles/     # Collected static assets
├── Dockerfile       # Production container
├── docker-compose.yml # Development orchestration
└── manage.py        # Django management

API Usage

DiffVault's engine is designed as a reusable library:

from engine.pipeline import run

result = run(
    old_code="def hello():\n    print('Hi')",
    new_code="def hello():\n    print('Hello, World!')",
    filename_hint="example.py",
    include_explanation=True,
    ai_provider="openai"
)

print(f"Language: {result.language}")
print(f"Changes: {result.stats.change_percentage}%")
print(f"AST Level: {result.diff_level_used}")
print(f"AI Explanation: {result.explanation}")

Production Deployment

Docker Production

# Build and run with Docker Compose
docker compose -f docker-compose.yml up --build -d

Environment Variables

# Required
SECRET_KEY=your-secure-secret-key-here
DEBUG=False
ALLOWED_HOSTS=yourdomain.com,localhost

# Optional (AI features)
OPENAI_API_KEY=sk-your-openai-key
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

Performance Notes

• Zero database required - Fully stateless architecture
• Memory efficient - Processes diffs in streaming fashion
• Fast startup - Django + Whitenoise for static serving
• Scalable - Horizontal scaling with load balancers

---

Technical Deep Dive

Diff Pipeline Flow

graph TD
    A[Input Code] --> B[Language Detection]
    B --> C[AST Parsing]
    C --> D[Myers Line Diff]
    D --> E[Token Inline Diff]
    E --> F[AST Structural Diff]
    F --> G[Change Classification]
    G --> H[Statistics Computation]
    H --> I[AI Explanation]
    I --> J[Unified Result]

Loading

Algorithm Complexity

Algorithm	Time Complexity	Space Complexity	Use Case
Myers	O(N+M+D²)	O(N+M)	Line-level changes
Inline Diff	O(L²)	O(L)	Character highlights
GumTree	O(N log N)	O(N)	AST structural changes
AI Explanation	Network I/O	O(1)	Plain-English context

Data Models

@dataclass
class DiffResult:
    language: str                    # Detected programming language
    hunks: list[DiffHunk]           # All change hunks with context
    stats: ChangeStats              # Comprehensive statistics
    change_types: list[ChangeType]   # Types of changes detected
    diff_level_used: DiffLevel      # Highest analysis level achieved
    explanation: Optional[str]      # AI-generated explanation
    patch: Optional[str]            # Unified diff patch format
    error: Optional[str]            # Error information if any

---

Comparison with Other Tools

Feature	DiffVault	GitHub Diff	PyCharm Diff	VS Code Diff
Multi-level analysis	✅ 4 levels	❌ 1 level	❌ 2 levels	❌ 1 level
AST structural diff	✅	❌	❌	❌
AI explanations	✅	❌	❌	❌
Language detection	✅ 20+	✅ Limited	✅ IDE-aware	✅ Extension-based
Move/rename detection	✅	❌	❌	❌
Inline highlights	✅	✅	✅	✅
Patch export	✅	✅	✅	✅
Zero setup	✅ Docker	❌ Requires account	❌ Requires IDE	❌ Requires editor
Self-hosted	✅	❌	❌	❌

---

Screenshots

DiffVault Interface in Action

---

Support & Community

• Bug Reports: GitHub Issues
• Feature Requests: GitHub Discussions
• Email: iamawaisgillani@gmail.com

---

Built for developers who demand the best diff experience

---

Made with ❤️ by the Syed Muhammad Awais Gillani