Zipster 📦

A modern, high-performance file compression and decompression web application powered by Huffman coding algorithm and WebAssembly.

✨ Features

• 🚀 High-Performance Compression: Utilizes Huffman coding algorithm compiled to WebAssembly for optimal speed
• 🌐 Modern Web Interface: Built with Next.js 15 and React 19 with a sleek, responsive design
• 📁 Drag & Drop Support: Intuitive file upload with drag-and-drop functionality
• 🔄 Bidirectional Processing: Both compression and decompression capabilities
• 📊 Compression Statistics: Real-time compression ratio and file size information
• 💾 Local File Management: Client-side file processing with download capabilities
• 🎨 Beautiful UI: Styled with Tailwind CSS and Radix UI components
• ⚡ Real-time Progress: Live progress tracking during compression/decompression
• 🌙 Dark Mode Support: Built-in dark/light theme toggle

🏗️ Architecture

Zipster follows a hybrid architecture combining the power of C++ algorithms with modern web technologies:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Frontend      │    │   API Routes     │    │  WASM Core      │
│   (Next.js)     │◄──►│   (Next.js)      │◄──►│  (C++ Huffman)  │
│                 │    │                  │    │                 │
│ • File Upload   │    │ • /api/compress  │    │ • Huffman Tree  │
│ • Progress UI   │    │ • /api/decompress│    │ • Serialization │
│ • File Download │    │ • WASM Loading   │    │ • Bit Encoding  │
└─────────────────┘    └──────────────────┘    └─────────────────┘

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm/yarn
• A C++ compiler (for building WASM module)
• Emscripten (for WebAssembly compilation)

Installation

1. Clone the repository

   git clone https://github.com/pandarudra/Zipster.git
   cd Zipster

2. Install dependencies

   cd web
   npm install

3. Build the WASM module (if needed)

   cd ../huffman-core
   # Compile C++ to WebAssembly
   emcc huffman.cpp -o huffman.wasm -s EXPORTED_FUNCTIONS="['_compress','_decompress','_malloc','_free']" -s ALLOW_MEMORY_GROWTH=1
   # Copy WASM files to web directory
   cp huffman.wasm ../web/lib/
   cp huffman.wasm ../web/public/

4. Run the development server

   cd ../web
   npm run dev

5. Open your browser Navigate to http://localhost:3000 to start using Zipster!

📂 Project Structure

Zipster/
├── 📁 huffman-core/          # Core Huffman algorithm implementation
│   ├── huffman.cpp           # C++ Huffman coding implementation
│   ├── input.txt            # Test input file
│   └── huffman.wasm         # Compiled WebAssembly module
│
├── 📁 web/                   # Next.js web application
│   ├── 📁 app/              # App router (Next.js 13+)
│   │   ├── layout.tsx       # Root layout component
│   │   ├── page.tsx         # Main application page
│   │   └── 📁 api/          # API routes
│   │       ├── compress/    # Compression endpoint
│   │       └── decompress/  # Decompression endpoint
│   │
│   ├── 📁 components/       # React components
│   │   ├── compression-mode-selector.tsx
│   │   ├── file-upload.tsx
│   │   ├── hero-section.tsx
│   │   ├── processing-card.tsx
│   │   ├── storage-manager.tsx
│   │   └── 📁 ui/          # Reusable UI components (Radix)
│   │
│   ├── 📁 lib/             # Utility libraries
│   │   ├── file-utils.ts   # File handling utilities
│   │   ├── huffman-wrapper.js
│   │   ├── huffman.js
│   │   ├── huffman.wasm    # WASM module
│   │   ├── loadHuffman.ts  # WASM loader
│   │   └── utils.ts        # General utilities
│   │
│   ├── 📁 hooks/           # Custom React hooks
│   ├── 📁 public/          # Static assets
│   ├── 📁 types/           # TypeScript type definitions
│   └── package.json        # Dependencies and scripts
│
└── README.md               # This file

🔧 Core Components

Huffman Algorithm (C++)

• Location: huffman-core/huffman.cpp
• Features:
  • Efficient Huffman tree construction
  • Tree serialization for decompression
  • Optimized bit-level encoding/decoding
  • Memory-safe operations

WASM Integration

• Loader: web/lib/loadHuffman.ts
• Wrapper: web/lib/huffman-wrapper.js
• Features:
  • Dynamic WASM module loading
  • Memory management
  • Type-safe interfaces

API Endpoints

• Compression: POST /api/compress
• Decompression: POST /api/decompress
• Features:
  • Base64 file encoding
  • Progress tracking
  • Error handling

Frontend Components

• FileUpload: Drag-and-drop file selection
• CompressionModeSelector: Toggle between compress/decompress modes
• ProcessingCard: Real-time progress and statistics
• StorageManager: File download and management

🛠️ Development

Building the WASM Module

To modify the Huffman algorithm or rebuild the WebAssembly module:

cd huffman-core

# Install Emscripten (if not already installed)
# Follow instructions at: https://emscripten.org/docs/getting_started/downloads.html

# Compile C++ to WebAssembly
emcc huffman.cpp -o huffman.wasm \
  -s EXPORTED_FUNCTIONS="['_compress','_decompress','_malloc','_free']" \
  -s ALLOW_MEMORY_GROWTH=1 \
  -s MODULARIZE=1 \
  -s EXPORT_NAME="createHuffmanModule" \
  -O3

# Copy to web directories
cp huffman.wasm ../web/lib/
cp huffman.wasm ../web/public/

Development Scripts

# Development server with Turbopack
npm run dev

# Production build
npm run build

# Start production server
npm run start

# Lint code
npm run lint

Adding New Features

1. Algorithm Changes: Modify huffman-core/huffman.cpp and rebuild WASM
2. UI Components: Add to web/components/ following the existing pattern
3. API Endpoints: Create new routes in web/app/api/
4. Utilities: Add helper functions to web/lib/

🧪 Testing

Manual Testing

1. Upload various file types (text, images, documents)
2. Test compression and decompression cycles
3. Verify file integrity after decompression
4. Test drag-and-drop functionality
5. Check compression ratios and performance

File Format Support

• ✅ Text files (.txt, .md, .json, .xml)
• ✅ Documents (.pdf, .doc, .docx)
• ✅ Images (.jpg, .png, .gif, .bmp)
• ✅ Archives (.zip, .tar, .gz)
• ✅ Code files (.js, .ts, .cpp, .py, etc.)

📊 Performance

Zipster achieves excellent compression performance through:

• WebAssembly Speed: Near-native C++ performance in the browser
• Huffman Efficiency: Optimal compression ratios for most file types
• Streaming Processing: Handles large files efficiently
• Memory Management: Optimized memory usage with automatic cleanup

Typical Compression Ratios

• Text files: 40-60% reduction
• Source code: 50-70% reduction
• Documents: 30-50% reduction
• Already compressed files: 0-10% reduction

🤝 Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes:
   • Follow the existing code style
   • Add comments for complex logic
   • Test your changes thoroughly
4. Commit your changes: git commit -m 'Add amazing feature'
5. Push to your branch: git push origin feature/amazing-feature
6. Open a Pull Request

Areas for Contribution

• 🔧 Performance optimizations
• 🎨 UI/UX improvements
• 📚 Documentation enhancements
• 🧪 Additional test cases
• 🌐 Internationalization
• 📱 Mobile responsiveness

📜 License

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

🙏 Acknowledgments

• Huffman Coding Algorithm: Created by David A. Huffman in 1952
• Next.js Team: For the amazing React framework
• Radix UI: For the beautiful component primitives
• Emscripten: For making C++ → WASM compilation seamless
• Tailwind CSS: For the utility-first CSS framework

📞 Contact

• Author: Rudra Panda
• GitHub: @pandarudra
• Project: Zipster Repository

---

Made with ❤️ and lots of ☕

Star ⭐ this repo if you found it helpful!