# bhargeshjani03/huffman-coding architecture

> Architecture diagram of the GitHub repository bhargeshjani03/huffman-coding, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhargeshjani03/huffman-coding
- Repository: https://github.com/bhargeshjani03/huffman-coding

## Overview

This is a lossless Huffman-compression application for MNIST model parameters, with a Flask dashboard for results and byte-distribution analysis. The main workflow trains a model, extracts its tensor bytes and reconstruction manifest, encodes them into a HUFC container, decodes and verifies the recovered model, and records metrics. The diagram follows the sampled integration and module calls; dashboard template wiring and some training details are not fully shown, so uncertain links are omitted.

Main entry points: [`scripts/integrate_mnist.py`](https://github.com/bhargeshjani03/huffman-coding/blob/main/scripts/integrate_mnist.py) (Compression Integration), [`web/app.py`](https://github.com/bhargeshjani03/huffman-coding/blob/main/web/app.py) (Flask Dashboard), [`src/encoder.py`](https://github.com/bhargeshjani03/huffman-coding/blob/main/src/encoder.py) (Payload Encoder), [`src/huffman_tree.py`](https://github.com/bhargeshjani03/huffman-coding/blob/main/src/huffman_tree.py) (Huffman Tree)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["MNIST Model"]
  node_training["MNIST Training<br/>[train_mnist.py]"]
  node_mnist["MNIST Model<br/>[model.py]"]
  node_checkpoint["Model Checkpoint<br/>[mnist_model.pth]"]
end

subgraph group_compression["Huffman Compression"]
  node_integration["Compression Integration<br/>[integrate_mnist.py]"]
  node_tensorbytes["Tensor Payload<br/>[tensor_payload.py]"]
  node_frequency["Byte Frequencies<br/>[frequency.py]"]
  node_tree["Huffman Tree<br/>[huffman_tree.py]"]
  node_heap["Min Heap<br/>[min_heap.py]"]
  node_node["Tree Nodes<br/>[node.py]"]
  node_encoder["Payload Encoder<br/>[encoder.py]"]
  node_bitstream["Bit Packing<br/>[bitstream.py]"]
  node_container["HUFC Container"]
  node_compressed["Compressed Model<br/>[mnist_model.huf]"]
end

subgraph group_reconstruction["Reconstruction And Validation"]
  node_decoder["Container Decoder<br/>[decoder.py]"]
  node_verification["Tensor Verification<br/>[verification.py]"]
  node_metrics["Compression Metrics<br/>[metrics.py]"]
end

subgraph group_dashboard["Dashboard And Results"]
  node_dashboard["Flask Dashboard<br/>[app.py]"]
  node_dashboardui["Dashboard Interface<br/>[index.html]"]
  node_results["Compression Results"]
end

node_engineer(("User"))

node_engineer -->|"requests dashboard"| node_dashboard
node_dashboard -->|"renders page"| node_dashboardui
node_dashboard -->|"runs compression"| node_integration
node_dashboard -->|"reads results"| node_results
node_dashboard -->|"reads container"| node_compressed
node_dashboard -->|"decodes for analysis"| node_decoder
node_dashboard -->|"builds analysis tree"| node_tree
node_training -->|"uses model"| node_mnist
node_training -.->|"produces checkpoint"| node_checkpoint
node_integration -->|"loads checkpoint"| node_checkpoint
node_integration -->|"loads model"| node_mnist
node_integration -->|"extracts tensors"| node_tensorbytes
node_integration -->|"builds container"| node_container
node_integration -->|"writes container"| node_compressed
node_integration -->|"decodes container"| node_decoder
node_integration -->|"checks reconstruction"| node_verification
node_integration -->|"calculates metrics"| node_metrics
node_integration -->|"writes results"| node_results
node_container -->|"encodes payload"| node_encoder
node_encoder -->|"counts bytes"| node_frequency
node_encoder -->|"builds codebook"| node_tree
node_encoder -->|"packs codes"| node_bitstream
node_tree -->|"prioritizes nodes"| node_heap
node_tree -->|"creates nodes"| node_node
node_decoder -->|"reads format constants"| node_container
node_verification -->|"restores model"| node_mnist

click node_training "https://github.com/bhargeshjani03/huffman-coding/blob/main/scripts/train_mnist.py"
click node_mnist "https://github.com/bhargeshjani03/huffman-coding/blob/main/src/model.py"
click node_checkpoint "https://github.com/bhargeshjani03/huffman-coding/blob/main/checkpoints/mnist_model.pth"
click node_integration "https://github.com/bhargeshjani03/huffman-coding/blob/main/scripts/integrate_mnist.py"
click node_tensorbytes "https://github.com/bhargeshjani03/huffman-coding/blob/main/src/tensor_payload.py"
click node_frequency "https://github.com/bhargeshjani03/huffman-coding/blob/main/src/frequency.py"
click node_tree "https://github.com/bhargeshjani03/huffman-coding/blob/main/src/huffman_tree.py"
click node_heap "https://github.com/bhargeshjani03/huffman-coding/blob/main/src/min_heap.py"
click node_node "https://github.com/bhargeshjani03/huffman-coding/blob/main/src/node.py"
click node_encoder "https://github.com/bhargeshjani03/huffman-coding/blob/main/src/encoder.py"
click node_bitstream "https://github.com/bhargeshjani03/huffman-coding/blob/main/src/bitstream.py"
click node_container "https://github.com/bhargeshjani03/huffman-coding/blob/main/src/container_format.py"
click node_compressed "https://github.com/bhargeshjani03/huffman-coding/blob/main/checkpoints/mnist_model.huf"
click node_decoder "https://github.com/bhargeshjani03/huffman-coding/blob/main/src/decoder.py"
click node_verification "https://github.com/bhargeshjani03/huffman-coding/blob/main/src/verification.py"
click node_metrics "https://github.com/bhargeshjani03/huffman-coding/blob/main/src/metrics.py"
click node_dashboard "https://github.com/bhargeshjani03/huffman-coding/blob/main/web/app.py"
click node_dashboardui "https://github.com/bhargeshjani03/huffman-coding/blob/main/web/templates/index.html"
click node_results "https://github.com/bhargeshjani03/huffman-coding/blob/main/checkpoints/compression_results.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_training,node_mnist,node_checkpoint,node_engineer toneBlue
class node_integration,node_tensorbytes,node_frequency,node_tree,node_heap,node_node,node_encoder,node_bitstream,node_container,node_compressed toneAmber
class node_decoder,node_verification,node_metrics toneMint
class node_dashboard,node_dashboardui,node_results toneRose
```

## Components

### MNIST Model

- [MNIST Training](https://github.com/bhargeshjani03/huffman-coding/blob/main/scripts/train_mnist.py): `scripts/train_mnist.py`
- [MNIST Model](https://github.com/bhargeshjani03/huffman-coding/blob/main/src/model.py): `src/model.py`
- [Model Checkpoint](https://github.com/bhargeshjani03/huffman-coding/blob/main/checkpoints/mnist_model.pth): `checkpoints/mnist_model.pth`

### Huffman Compression

- [Compression Integration](https://github.com/bhargeshjani03/huffman-coding/blob/main/scripts/integrate_mnist.py): `scripts/integrate_mnist.py`
- [Tensor Payload](https://github.com/bhargeshjani03/huffman-coding/blob/main/src/tensor_payload.py): `src/tensor_payload.py`
- [Byte Frequencies](https://github.com/bhargeshjani03/huffman-coding/blob/main/src/frequency.py): `src/frequency.py`
- [Huffman Tree](https://github.com/bhargeshjani03/huffman-coding/blob/main/src/huffman_tree.py): `src/huffman_tree.py`
- [Min Heap](https://github.com/bhargeshjani03/huffman-coding/blob/main/src/min_heap.py): `src/min_heap.py`
- [Tree Nodes](https://github.com/bhargeshjani03/huffman-coding/blob/main/src/node.py): `src/node.py`
- [Payload Encoder](https://github.com/bhargeshjani03/huffman-coding/blob/main/src/encoder.py): `src/encoder.py`
- [Bit Packing](https://github.com/bhargeshjani03/huffman-coding/blob/main/src/bitstream.py): `src/bitstream.py`
- [HUFC Container](https://github.com/bhargeshjani03/huffman-coding/blob/main/src/container_format.py): `src/container_format.py`
- [Compressed Model](https://github.com/bhargeshjani03/huffman-coding/blob/main/checkpoints/mnist_model.huf): `checkpoints/mnist_model.huf`

### Reconstruction And Validation

- [Container Decoder](https://github.com/bhargeshjani03/huffman-coding/blob/main/src/decoder.py): `src/decoder.py`
- [Tensor Verification](https://github.com/bhargeshjani03/huffman-coding/blob/main/src/verification.py): `src/verification.py`
- [Compression Metrics](https://github.com/bhargeshjani03/huffman-coding/blob/main/src/metrics.py): `src/metrics.py`

### Dashboard And Results

- [Flask Dashboard](https://github.com/bhargeshjani03/huffman-coding/blob/main/web/app.py): `web/app.py`
- [Dashboard Interface](https://github.com/bhargeshjani03/huffman-coding/blob/main/web/templates/index.html): `web/templates/index.html`
- [Compression Results](https://github.com/bhargeshjani03/huffman-coding/blob/main/checkpoints/compression_results.json): `checkpoints/compression_results.json`

### Other components

- **User**

## Connections

- User → Flask Dashboard: requests dashboard (evidence: `web/app.py`)
- Flask Dashboard → Dashboard Interface: renders page (evidence: `web/app.py`)
- Flask Dashboard → Compression Integration: runs compression (evidence: `web/app.py`)
- Flask Dashboard → Compression Results: reads results (evidence: `web/app.py`)
- Flask Dashboard → Compressed Model: reads container (evidence: `web/app.py`)
- Flask Dashboard → Container Decoder: decodes for analysis (evidence: `web/app.py`)
- Flask Dashboard → Huffman Tree: builds analysis tree (evidence: `web/app.py`)
- MNIST Training → MNIST Model: uses model (evidence: `scripts/train_mnist.py`)
- MNIST Training → Model Checkpoint: produces checkpoint
- Compression Integration → Model Checkpoint: loads checkpoint (evidence: `scripts/integrate_mnist.py`)
- Compression Integration → MNIST Model: loads model (evidence: `scripts/integrate_mnist.py`)
- Compression Integration → Tensor Payload: extracts tensors (evidence: `scripts/integrate_mnist.py`)
- Compression Integration → HUFC Container: builds container (evidence: `scripts/integrate_mnist.py`)
- Compression Integration → Compressed Model: writes container (evidence: `scripts/integrate_mnist.py`)
- Compression Integration → Container Decoder: decodes container (evidence: `scripts/integrate_mnist.py`)
- Compression Integration → Tensor Verification: checks reconstruction (evidence: `scripts/integrate_mnist.py`)
- Compression Integration → Compression Metrics: calculates metrics (evidence: `scripts/integrate_mnist.py`)
- Compression Integration → Compression Results: writes results (evidence: `scripts/integrate_mnist.py`)
- HUFC Container → Payload Encoder: encodes payload (evidence: `src/container_format.py`)
- Payload Encoder → Byte Frequencies: counts bytes (evidence: `src/encoder.py`)
- Payload Encoder → Huffman Tree: builds codebook (evidence: `src/encoder.py`)
- Payload Encoder → Bit Packing: packs codes (evidence: `src/encoder.py`)
- Huffman Tree → Min Heap: prioritizes nodes (evidence: `src/huffman_tree.py`)
- Huffman Tree → Tree Nodes: creates nodes (evidence: `src/huffman_tree.py`)
- Container Decoder → HUFC Container: reads format constants (evidence: `src/decoder.py`)
- Tensor Verification → MNIST Model: restores model (evidence: `src/verification.py`)
