Compression Explorer

An interactive, traceable compression visualization system. Upload any text file → see every LZ77 decision, Huffman tree construction, and the final bitstream — all backed by real algorithm data.

---

Project Structure

compression-explorer/
├── backend/        Python FastAPI — compression engine + trace builder
└── frontend/       React + Vite — all visualizations

---

Backend Setup

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

API available at http://localhost:8000

Endpoints:

• POST /api/analyze — upload a text file, get full compression trace
• GET /api/example — load built-in sample trace (no upload needed)
• GET /api/health — health check

---

Frontend Setup

cd frontend
npm install
npm run dev

App available at http://localhost:5173

The Vite dev server proxies /api → http://localhost:8000 automatically.

---

What's Built

Backend pipeline

Upload file
→ Build spans (char-level, stable IDs)
→ Build symbols (frequency table)
→ Pattern detection (word/phrase level)
→ LZ77 trace (literal + match events, candidates)
→ Huffman tree build (step-by-step merge events)
→ Bitstream generation (cross-linked to LZ77 events)
→ Artifact sections (header / codebook / payload)
→ Insights (entropy, verdict, top patterns)
→ Return full CompressionTrace JSON

Frontend panels

Panel	What it shows
Scorecard	Size, ratio, entropy, compressibility verdict
Heatmap	Text colored by repetition intensity; click pattern → highlight all occurrences
LZ77 Timeline	Step through every event; sliding window + match arrows; candidate list
Huffman Tree	D3 tree animated step-by-step; 0/1 edge labels; symbol codes at leaves
Bitstream View	Color-coded bit grid; hover → full provenance chain
File Anatomy	Proportional header/codebook/payload breakdown; click for explanation

Schema design

Every object has a stable ID (sp_, sym_, pat_, n_, lz_, bit_). The bitstream links back to LZ77 events (lz77_event_id). LZ77 events link to spans (span_id) and symbols (symbol_id). Frontend resolves the full chain: span → pattern → LZ77 event → symbol → bits.

---

Constraints (V1)

• Text files only (.txt, .md, .csv, .json etc.)
• Max 50 KB input
• UTF-8 encoding required
• Simplified DEFLATE (not spec-compliant — built for visualization clarity)