Jv-compression-tool

jv-compression-tool is a pure Python implementation of lossless Huffman compression, built from scratch to explore how compression works at a low level. It includes both a compressor and decompressor, designed as a clean, reusable library with a strong focus on correctness and test coverage.

What this project demonstrates:

Algorithm implementation — frequency analysis, Huffman tree construction, and deterministic code generation

Binary data handling — packing/unpacking bitstreams, tracking padding, and converting between bytes and bits

Software design — clear module boundaries, reusable utilities, and maintainable project structure

Test-driven development — comprehensive unit and integration tests covering edge cases and full workflows

Packaging — structured as a distributable Python package with versioning and documentation

How it works:

The compression pipeline follows the full Huffman workflow: build a frequency table, construct a min-heap, generate a Huffman tree, produce a code map, and encode the input into a compact bitstream. The output includes a custom header format that stores metadata (such as padding length and symbol frequencies) so the decompressor can reliably reconstruct the original content.

The current version is primarily designed and tested for text-based data (UTF-8). The underlying Huffman implementation can technically compress any byte sequence, and future updates may expand the high-level API to handle arbitrary binary formats more robustly.

Interactive demo:

This project is also designed to be showcased as an interactive demo page, where users can compress and decompress input directly in the browser and see the workflow step by step (frequency table, tree, and encoded output). The goal is to make the compression pipeline visible and easy to understand, while still demonstrating real backend logic.

Key challenges solved:

Designing a modular architecture — separating frequency analysis, tree building, code mapping, header encoding/decoding, and I/O into focused modules

Implementing a min-heap from scratch — sift-up/sift-down, push/pop operations, and validation tests

Building a complete Huffman workflow — handling empty input, single-symbol input, and deterministic merges

Bit-level manipulation — packing variable-length codes into bytes and correctly restoring them during decoding

Creating a custom header format — storing metadata so decompression is reliable and deterministic

Building this project strengthened my understanding of algorithms, recursion, binary data handling, and how to design code that is easy to reason about and extend.