# petrosgeorgiouu/huffcompression-lab architecture

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

- Interactive diagram: https://gitdiagram.com/petrosgeorgiouu/huffcompression-lab
- Repository: https://github.com/petrosgeorgiouu/huffcompression-lab

## Overview

This is a C++17 Huffman file codec. The principal workflow is a user invoking compression or decompression on files: compression scans byte frequencies, builds and serializes a Huffman tree, then writes encoded data; decompression reads the archive header and tree, then decodes blocks to an output file. The repository also documents corpus-ratio measurement and whole-file performance benchmarks. Core call relationships are supported by the sampled compression and decoder code and the SOURCE INDEX; unsampled decompression and measurement links rely on README documentation, so their internal steps are not expanded.

Main entry points: [`src/Compression.cpp`](https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/Compression.cpp) (Compressor), [`src/Decompression.cpp`](https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/Decompression.cpp) (Decompressor), [`src/HuffmanTree.cpp`](https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/HuffmanTree.cpp) (Huffman tree), [`apps/huff.cpp`](https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/apps/huff.cpp) (Compression CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_codec["Codec workflows"]
  node_compress_cli["Compression CLI<br/>[huff.cpp]"]
  node_compressor["Compressor<br/>[Compression.cpp]"]
  node_decompress_cli["Decompression CLI<br/>[dehuff.cpp]"]
  node_decompressor["Decompressor<br/>[Decompression.cpp]"]
end

subgraph group_encoding["Encoding internals"]
  node_frequency["Frequency scan<br/>[FrequencyTable.cpp]"]
  node_tree["Huffman tree<br/>[HuffmanTree.cpp]"]
  node_priority["Priority queue"]
  node_bitwriter["Bit writer<br/>[BitWriter.cpp]"]
end

subgraph group_decoding["Decoding internals"]
  node_bitreader["Bit reader<br/>[BitReader.cpp]"]
  node_decoder["Huffman decoder<br/>[HuffmanDecoder.cpp]"]
end

subgraph group_measurement["Measurements"]
  node_corpus["Corpus measurements<br/>[corpus.cpp]"]
  node_profilers["Performance benchmarks"]
end

node_user(("User"))
node_input["Input file"]
node_archive["Huffman archive"]
node_output["Decoded file"]
node_corpus_files["Text corpus"]
node_benchmark_files["Benchmark workloads"]

node_user -->|"invokes"| node_compress_cli
node_compress_cli -->|"calls"| node_compressor
node_compressor -->|"reads"| node_input
node_compressor -->|"scans frequencies"| node_frequency
node_compressor -->|"builds tree"| node_tree
node_tree -->|"uses queue"| node_priority
node_compressor -->|"writes archive"| node_bitwriter
node_tree -->|"serializes tree"| node_bitwriter
node_compressor -->|"writes"| node_archive
node_user -->|"invokes"| node_decompress_cli
node_decompress_cli -->|"calls"| node_decompressor
node_decompressor -->|"reads"| node_archive
node_decompressor -->|"reads bits"| node_bitreader
node_decompressor -->|"decodes with"| node_decoder
node_decoder -->|"consumes bits"| node_bitreader
node_decompressor -->|"writes"| node_output
node_user -->|"runs"| node_corpus
node_corpus -->|"measures"| node_corpus_files
node_user -->|"runs"| node_profilers
node_profilers -->|"processes"| node_benchmark_files

click node_compress_cli "https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/apps/huff.cpp"
click node_compressor "https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/Compression.cpp"
click node_frequency "https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/FrequencyTable.cpp"
click node_tree "https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/HuffmanTree.cpp"
click node_priority "https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/include/huffman/UniquePtrPriorityQueue.hpp"
click node_bitwriter "https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/BitWriter.cpp"
click node_decompress_cli "https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/apps/dehuff.cpp"
click node_decompressor "https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/Decompression.cpp"
click node_bitreader "https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/BitReader.cpp"
click node_decoder "https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/HuffmanDecoder.cpp"
click node_corpus "https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/benchmarks/corpus.cpp"
click node_profilers "https://github.com/petrosgeorgiouu/huffcompression-lab/tree/main/benchmarks"

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_compress_cli,node_compressor,node_decompress_cli,node_decompressor,node_user toneBlue
class node_frequency,node_tree,node_priority,node_bitwriter toneAmber
class node_bitreader,node_decoder toneMint
class node_corpus,node_profilers toneRose
class node_input,node_archive,node_output,node_corpus_files,node_benchmark_files toneIndigo
```

## Components

### Codec workflows

- [Compression CLI](https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/apps/huff.cpp): `apps/huff.cpp`
- [Compressor](https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/Compression.cpp): `src/Compression.cpp`
- [Decompression CLI](https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/apps/dehuff.cpp): `apps/dehuff.cpp`
- [Decompressor](https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/Decompression.cpp): `src/Decompression.cpp`

### Encoding internals

- [Frequency scan](https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/FrequencyTable.cpp): `src/FrequencyTable.cpp`
- [Huffman tree](https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/HuffmanTree.cpp): `src/HuffmanTree.cpp`
- [Priority queue](https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/include/huffman/UniquePtrPriorityQueue.hpp): `include/huffman/UniquePtrPriorityQueue.hpp`
- [Bit writer](https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/BitWriter.cpp): `src/BitWriter.cpp`

### Decoding internals

- [Bit reader](https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/BitReader.cpp): `src/BitReader.cpp`
- [Huffman decoder](https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/src/HuffmanDecoder.cpp): `src/HuffmanDecoder.cpp`

### Measurements

- [Corpus measurements](https://github.com/petrosgeorgiouu/huffcompression-lab/blob/main/benchmarks/corpus.cpp): `benchmarks/corpus.cpp`
- [Performance benchmarks](https://github.com/petrosgeorgiouu/huffcompression-lab/tree/main/benchmarks): `benchmarks`

### Other components

- **User**
- **Input file**
- **Huffman archive**
- **Decoded file**
- **Text corpus**
- **Benchmark workloads**

## Connections

- User → Compression CLI: invokes (evidence: `apps/huff.cpp`)
- Compression CLI → Compressor: calls (evidence: `apps/huff.cpp`)
- Compressor → Input file: reads (evidence: `src/Compression.cpp`)
- Compressor → Frequency scan: scans frequencies (evidence: `src/Compression.cpp`)
- Compressor → Huffman tree: builds tree (evidence: `src/Compression.cpp`)
- Huffman tree → Priority queue: uses queue (evidence: `src/HuffmanTree.cpp`)
- Compressor → Bit writer: writes archive (evidence: `src/Compression.cpp`)
- Huffman tree → Bit writer: serializes tree (evidence: `src/HuffmanTree.cpp`)
- Compressor → Huffman archive: writes (evidence: `src/Compression.cpp`)
- User → Decompression CLI: invokes (evidence: `README.md`)
- Decompression CLI → Decompressor: calls (evidence: `README.md`)
- Decompressor → Huffman archive: reads (evidence: `README.md`)
- Decompressor → Bit reader: reads bits (evidence: `src/Decompression.cpp`)
- Decompressor → Huffman decoder: decodes with (evidence: `src/Decompression.cpp`)
- Huffman decoder → Bit reader: consumes bits (evidence: `src/HuffmanDecoder.cpp`)
- Decompressor → Decoded file: writes (evidence: `README.md`)
- User → Corpus measurements: runs (evidence: `README.md`)
- Corpus measurements → Text corpus: measures (evidence: `README.md`)
- User → Performance benchmarks: runs (evidence: `README.md`)
- Performance benchmarks → Benchmark workloads: processes (evidence: `README.md`)
