# se-team14-mini-project/file-compression-tool architecture

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

- Interactive diagram: https://gitdiagram.com/se-team14-mini-project/file-compression-tool
- Repository: https://github.com/se-team14-mini-project/file-compression-tool

## Overview

This is a C++17 command-line utility for lossless single-file compression and decompression using a custom Huffman-based `.huf` format, with archive inspection and safety checks. The main workflow is CLI command dispatch → controller orchestration → file validation, Huffman processing, archive serialization or parsing, and safe output publication. Metadata validation and decoded-file integrity checking are distinct safeguards; `info` inspects metadata without decoding. The README documents the planned component hand-offs, while excerpts show selected calls and validation behavior; links based only on the documented architecture cite the README.

Main entry points: [`src/controller.cpp`](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/controller.cpp) (Operation controller), [`src/main.cpp`](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/main.cpp) (Command dispatch), [`src/archive.cpp`](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/archive.cpp) (Archive read/write), [`include/interfaces.h`](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/include/interfaces.h) (Shared format contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_cli_entry["Command dispatch<br/>[main.cpp]"]
end

subgraph group_workflow["Compression workflow"]
  node_controller["Operation controller<br/>[controller.cpp]"]
  node_frequency["Frequency analysis<br/>[huffman.cpp]"]
  node_tree_codes["Tree and codes<br/>[huffman.cpp]"]
  node_bit_codec["Bit codec<br/>[huffman.cpp]"]
end

subgraph group_format["Archive format"]
  node_archive_io["Archive read/write<br/>[archive.cpp]"]
  node_format_contract["Shared format contract<br/>[interfaces.h]"]
end

subgraph group_safety["Validation and safety"]
  node_file_checks["File checks<br/>[file_io.cpp]"]
  node_metadata_validation["Metadata validation<br/>[validation.cpp]"]
  node_output_safety["Output path safety<br/>[validation.cpp]"]
  node_decoded_verification["Decoded-file verification<br/>[validation.cpp]"]
  node_crc["CRC32 handling<br/>[controller.cpp]"]
  node_safe_publish["Safe output publish<br/>[controller.cpp]"]
end

node_user(("User"))

node_user -->|"runs command"| node_cli_entry
node_cli_entry -->|"dispatches operations"| node_controller
node_cli_entry -->|"requests archive info"| node_controller
node_controller -->|"checks files"| node_file_checks
node_controller -->|"validates output"| node_output_safety
node_controller -->|"counts bytes"| node_frequency
node_frequency -->|"builds Huffman model"| node_tree_codes
node_controller -->|"builds tree and codes"| node_tree_codes
node_controller -->|"encodes or decodes"| node_bit_codec
node_controller -->|"writes or reads archive"| node_archive_io
node_archive_io -->|"checks structure"| node_metadata_validation
node_controller -->|"validates metadata"| node_metadata_validation
node_controller -->|"verifies restored file"| node_decoded_verification
node_controller -->|"checks checksum"| node_crc
node_controller -->|"publishes output"| node_safe_publish
node_archive_io -->|"uses format declarations"| node_format_contract
node_controller -->|"uses shared declarations"| node_format_contract
node_cli_entry -->|"uses result types"| node_format_contract

click node_cli_entry "https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/main.cpp"
click node_controller "https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/controller.cpp"
click node_file_checks "https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/file_io.cpp"
click node_frequency "https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/huffman.cpp"
click node_tree_codes "https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/huffman.cpp"
click node_bit_codec "https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/huffman.cpp"
click node_archive_io "https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/archive.cpp"
click node_metadata_validation "https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/validation.cpp"
click node_output_safety "https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/validation.cpp"
click node_decoded_verification "https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/validation.cpp"
click node_crc "https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/controller.cpp"
click node_safe_publish "https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/controller.cpp"
click node_format_contract "https://github.com/se-team14-mini-project/file-compression-tool/blob/main/include/interfaces.h"

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_cli_entry,node_user toneBlue
class node_controller,node_frequency,node_tree_codes,node_bit_codec toneAmber
class node_archive_io,node_format_contract toneMint
class node_file_checks,node_metadata_validation,node_output_safety,node_decoded_verification,node_crc,node_safe_publish toneRose
```

## Components

### CLI

- [Command dispatch](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/main.cpp): `src/main.cpp`

### Compression workflow

- [Operation controller](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/controller.cpp): `src/controller.cpp`
- [Frequency analysis](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/huffman.cpp): `src/huffman.cpp`
- [Tree and codes](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/huffman.cpp): `src/huffman.cpp`
- [Bit codec](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/huffman.cpp): `src/huffman.cpp`

### Archive format

- [Archive read/write](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/archive.cpp): `src/archive.cpp`
- [Shared format contract](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/include/interfaces.h): `include/interfaces.h`

### Validation and safety

- [File checks](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/file_io.cpp): `src/file_io.cpp`
- [Metadata validation](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/validation.cpp): `src/validation.cpp`
- [Output path safety](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/validation.cpp): `src/validation.cpp`
- [Decoded-file verification](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/validation.cpp): `src/validation.cpp`
- [CRC32 handling](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/controller.cpp): `src/controller.cpp`
- [Safe output publish](https://github.com/se-team14-mini-project/file-compression-tool/blob/main/src/controller.cpp): `src/controller.cpp`

### Other components

- **User**

## Connections

- User → Command dispatch: runs command (evidence: `README.md`)
- Command dispatch → Operation controller: dispatches operations (evidence: `src/main.cpp`)
- Command dispatch → Operation controller: requests archive info (evidence: `src/main.cpp`)
- Operation controller → File checks: checks files (evidence: `README.md`)
- Operation controller → Output path safety: validates output (evidence: `README.md`)
- Operation controller → Frequency analysis: counts bytes (evidence: `src/controller.cpp`)
- Frequency analysis → Tree and codes: builds Huffman model (evidence: `README.md`)
- Operation controller → Tree and codes: builds tree and codes (evidence: `README.md`)
- Operation controller → Bit codec: encodes or decodes (evidence: `src/controller.cpp`)
- Operation controller → Archive read/write: writes or reads archive (evidence: `README.md`)
- Archive read/write → Metadata validation: checks structure (evidence: `src/archive.cpp`)
- Operation controller → Metadata validation: validates metadata (evidence: `README.md`)
- Operation controller → Decoded-file verification: verifies restored file (evidence: `README.md`)
- Operation controller → CRC32 handling: checks checksum (evidence: `README.md`)
- Operation controller → Safe output publish: publishes output (evidence: `src/controller.cpp`)
- Archive read/write → Shared format contract: uses format declarations (evidence: `README.md`)
- Operation controller → Shared format contract: uses shared declarations (evidence: `README.md`)
- Command dispatch → Shared format contract: uses result types (evidence: `README.md`)