Skip to content

Commit 6665efd

Browse files
subha0319subha0319
committed
Update README.md
1 parent f8b2b11 commit 6665efd

1 file changed

Lines changed: 215 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 215 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,215 @@
1-
# Huffman-Coding-API
2-
This project aims to solve this by creating a web service that implements Huffman coding, a lossless data compression algorithm, to reduce the size of text data for more efficient storage and transmission.
1+
# Huffman Coding API & Visualizer
2+
3+
A full-stack web application that provides a real-time, interactive tool to demonstrate Huffman coding, a fundamental lossless data compression algorithm. This project was built to showcase the practical application of Data Structures and Algorithms (DSA) concepts in a modern, deployed web environment.
4+
5+
**Live Application Link:** [https://huffman-coding-api-sqe8.onrender.com](https://huffman-coding-api-sqe8.onrender.com)
6+
7+
*(Note: The free hosting instance may spin down due to inactivity, causing a slight delay of up to 50 seconds on the first load.)*
8+
9+
10+
---
11+
12+
## Features
13+
14+
- **Compress Text**: Accepts any string of text and returns the Huffman-encoded binary string and the corresponding character-to-code mapping table.
15+
- **Decompress Text**: Accepts an encoded binary string and its code table to perfectly reconstruct the original text.
16+
- **Live Stats**: Instantly calculates and displays the original size, compressed size, and the resulting compression ratio.
17+
- **RESTful Backend API**: A robust backend built with Spring Boot to handle all the complex compression/decompression logic.
18+
- **Responsive React UI**: A clean, simple, and responsive user interface built with React for a seamless user experience.
19+
20+
---
21+
22+
## Real-World Use Cases of Huffman Coding
23+
24+
While this project is a visualizer, Huffman coding is a foundational algorithm used in many real-world technologies:
25+
26+
- **File Compression:** It is a key component in compression tools like **PKZIP** (the format used by `.zip` files) and **GZIP**.
27+
- **Media Formats:** Multimedia formats such as **JPEG** for images, **MP3** for audio, and **MPEG** for video use Huffman coding as part of their compression process to reduce file sizes.
28+
- **Network Communication:** It's used to reduce the amount of data that needs to be transmitted over networks, improving speed and efficiency.
29+
30+
---
31+
32+
## Tech Stack
33+
34+
| Category | Technology |
35+
| ------------- | --------------------------------------------- |
36+
| **Backend** | Java 21, Spring Boot, Maven |
37+
| **Frontend** | React, JavaScript (ES6+), CSS3 |
38+
| **Deployment**| Render (Backend via Docker, Frontend as Static Site) |
39+
40+
---
41+
42+
## Project Structure
43+
44+
The project is a monorepo containing two main parts: the backend API and the frontend UI.
45+
```
46+
/
47+
├── backend/
48+
│ ├── src/main/java/com/github/subha0319/huffman\_api/
49+
│ │ ├── HuffmanApiApplication.java \# Main Spring Boot application
50+
│ │ ├── HuffmanController.java \# REST API endpoints
51+
│ │ ├── HuffmanService.java \# Core compression/decompression logic
52+
│ │ └── HuffmanNode.java \# Node for the Huffman Tree
53+
│ ├── src/test/java/ \# JUnit tests
54+
│ ├── pom.xml \# Maven configuration
55+
│ └── Dockerfile \# Docker configuration for deployment
56+
│
57+
└── frontend/
58+
│ ├── public/ \# Static assets and index.html
59+
│ ├── src/
60+
│ │ ├── App.js \# Main React component and UI logic
61+
│ │ ├── App.css \# Styles for the App component
62+
│ │ └── index.css \# Global styles
63+
│ ├── package.json \# NPM dependencies and scripts
64+
└── .gitignore \# Files to ignore for Node.js
65+
66+
```
67+
---
68+
69+
## Local Development Setup
70+
71+
### Prerequisites
72+
73+
- Java JDK 21 or later
74+
- Maven 3.8+
75+
- Node.js v14+ and npm
76+
77+
### 1. Configure for Local Environment
78+
79+
For local testing, the frontend needs to connect to the local backend server.
80+
81+
- In `frontend/src/App.js`, ensure the `API_URL` constant is set to the local address:
82+
```javascript
83+
const API_URL = 'http://localhost:8080/api';
84+
```
85+
- In `backend/src/main/java/com/github/subha0319/huffman_api/HuffmanController.java`, ensure the `@CrossOrigin` annotation points to the local frontend:
86+
```java
87+
@CrossOrigin(origins = "http://localhost:3000")
88+
```
89+
90+
### 2. Run the Backend Server
91+
92+
```bash
93+
# Navigate to the backend directory
94+
cd backend
95+
96+
# Run the Spring Boot application (use mvnw.cmd on Windows)
97+
./mvnw spring-boot:run
98+
````
99+
100+
The backend API will now be running on `http://localhost:8080`.
101+
102+
### 3\. Run the Frontend Application
103+
104+
```bash
105+
# In a new terminal, navigate to the frontend directory
106+
cd frontend
107+
108+
# Install the necessary dependencies
109+
npm install
110+
111+
# Start the React development server
112+
npm start
113+
```
114+
115+
The frontend application will automatically open in your browser at `http://localhost:3000`.
116+
117+
-----
118+
119+
## How to Test the Application Locally
120+
121+
The backend includes a suite of JUnit tests to ensure the core algorithm works correctly across various edge cases.
122+
123+
To run these tests:
124+
125+
```bash
126+
# Navigate to the backend directory
127+
cd backend
128+
129+
# Run the Maven test command (use mvnw.cmd on Windows)
130+
./mvnw test
131+
```
132+
133+
The tests will execute, and you will see a `BUILD SUCCESS` message if all tests pass.
134+
135+
-----
136+
137+
## API Documentation
138+
139+
The backend exposes a simple REST API with two main endpoints.
140+
141+
### Compress Endpoint
142+
143+
- **URL**: `/api/compress`
144+
145+
- **Method**: `POST`
146+
147+
- **Description**: Takes a string of text and returns its compressed binary representation and the corresponding code table.
148+
149+
- **Request Body**:
150+
151+
```json
152+
{
153+
"text": "hello world"
154+
}
155+
```
156+
157+
- **Success Response (200 OK)**:
158+
159+
```json
160+
{
161+
"encodedText": "011011000100001111101010111011000",
162+
"codeTable": {
163+
" ": "00",
164+
"r": "010",
165+
"d": "011",
166+
"e": "100",
167+
"h": "1010",
168+
"w": "1011",
169+
"l": "110",
170+
"o": "111"
171+
}
172+
}
173+
```
174+
175+
### Decompress Endpoint
176+
177+
- **URL**: `/api/decompress`
178+
179+
- **Method**: `POST`
180+
181+
- **Description**: Takes a Huffman-encoded binary string and a code table to reconstruct the original text.
182+
183+
- **Request Body**:
184+
185+
```json
186+
{
187+
"encodedText": "011011000100001111101010111011000",
188+
"codeTable": {
189+
" ": "00",
190+
"r": "010",
191+
"d": "011",
192+
"e": "100",
193+
"h": "1010",
194+
"w": "1011",
195+
"l": "110",
196+
"o": "111"
197+
}
198+
}
199+
```
200+
201+
- **Success Response (200 OK)**:
202+
203+
```json
204+
{
205+
"text": "hello world"
206+
}
207+
```
208+
209+
-----
210+
211+
## Potential Improvements
212+
213+
- **File Uploads**: Allow users to upload `.txt` files for compression and download the compressed output.
214+
- **Visual Tree**: Render a visual representation of the Huffman Tree that is generated during the compression process.
215+
- **Enhanced Error Handling**: Provide more specific feedback to the user on the frontend for invalid inputs during decompression.

0 commit comments

Comments
 (0)