# karanm6505/huffstream architecture

> Architecture diagram of the GitHub repository karanm6505/huffstream, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karanm6505/huffstream
- Repository: https://github.com/karanm6505/huffstream

## Overview

##### Project Type and Purpose
- This is a full‑stack network application (not web‑based) implementing a client/server architecture.
- Purpose: Compress files using Huffman coding in the client, send them over TCP/IP with SSL/TLS, and decompress/save them on the server.

##### File Structure
- Top‑level directories:
– client/: CLI entry points and sample files to send
– server/: CLI entry points and storage for received files
– utils/: Huffman algorithm and file‑encode/decode utilities
– scripts/ (generate SSL certs, set up JSON configs)
– config/: server_config.json, client_config.json, SSL cert/key files
- Key config files drive behavior via JSON + environment variables.
- Utilities are reused by both client and server.

##### Architectural Patterns
- Classic client‑server with dual TCP channels:
– Control channel (commands, metadata)
– Data channel (binary file payload)
- Threaded/multi‑connection support (via NetworkManager).
- Separation of concerns: Networking vs. compression vs. CLI.

##### Main Components and Their Relationships
A. Client Application
– client.py / multi_client.py
– Reads file → calls Huffman encoder → passes compressed data to NetworkManager
B. Server Application
– server.py / multi_server.py
– NetworkManager receives data → writes compressed file → calls Huffman decoder → saves original
C. NetworkManager (in utils/network_manager.py)
– Wraps socket creation, SSL/TLS handshake (ssl module), threading, and dual‑channel management
– Provides a uniform API for send/receive on both client and server
D. Huffman Utilities (utils/huffman.py, encode_file.py, decode_file.py)
– Implements the frequency analysis, tree building, code table, padding, metadata storage
E. Configuration Subsystem
– JSON files in config/: define hosts, ports, SSL certs, buffer sizes, retry policy
– setup_config.py: copies templates and populates actual config files
F. Scripts (scripts/generate_certificates.py)
– Generate self‑signed certificates for SSL/TLS
G. External Dependencies
– Python standard libraries: ssl, socket, threading, json
– No external frameworks

- Use a layered layout from left (client) to right (server):
[Client CLI] → [Client NetworkManager] → [Network: Control/Data Channels] → [Server NetworkManager] → [Server CLI]
- Config subsystem feeding into both clients and servers (via environment variables/JSON).

##### Relationships and Data Flows
– Client CLI → Encoder → NetworkManager
– NetworkManager → (control channel) → NetworkManager on server
– NetworkManager → (data channel) → NetworkManager on server
– Server NetworkManager → Decoder → Server CLI (file storage)
– “TLS‑wrapped TCP” for both channels
– Header format (“<filename>|<filesize>”) on control channel
– Raw binary on data channel

##### Patterns & Principles
- Separation of concerns:
– CLI vs. compression logic vs. network logic vs. config management
- Modularity: utils are shared between client and server
- Thread safety: concurrent client support in multi_server.py via threading
- Security: SSL configuration via env vars + JSON, certificate verification modes

##### Summary Checklist
[ ] Main components: Client CLI, Huffman Encoder, NetworkManager, Network channels, Server NetworkManager, Huffman Decoder, Server CLI
[ ] Configuration subsystem (config files + env vars)
[ ] Operational scripts block (SSL cert gen, config setup)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client Side"
        direction TB
        ClientCLI["Client Application"]:::client
        SampleFiles["Sending Files Directory"]:::client
        Encoder["Huffman Encoder"]:::utils
        NetMgrClient["NetworkManager"]:::utils
        ClientCLI -->|"read files"| SampleFiles
        ClientCLI -->|calls Encoder| Encoder
        Encoder -->|provides compressed data| NetMgrClient
    end

    %% Network Layer
    subgraph "Network Layer"
        direction TB
        Cloud{{"Network\nControl & Data Channels"}}:::network
    end

    NetMgrClient -->|"<filename>|<filesize>\\nTLS-wrapped TCP (control)"| Cloud
    NetMgrClient -->|"Raw binary\\nTLS-wrapped TCP (data)"| Cloud

    %% Server Side
    subgraph "Server Side"
        direction TB
        NetMgrServer["NetworkManager"]:::utils
        Decoder["Huffman Decoder"]:::utils
        ServerCLI["Server Application"]:::server
        Storage(("Received Files Storage")):::storage
        Cloud -->|"<filename>|<filesize>\\nTLS-wrapped TCP (control)"| NetMgrServer
        Cloud -->|"Raw binary\\nTLS-wrapped TCP (data)"| NetMgrServer
        NetMgrServer -->|passes compressed data| Decoder
        Decoder -->|writes original files| ServerCLI
        ServerCLI -->|stores files| Storage
    end

    %% Operational Scripts
    subgraph "Operational Scripts" 
        direction TB
        CertScript["SSL Certificate Generation"]:::scripts
        TestSSL["SSL/TLS Connection Test"]:::scripts
    end

    %% Configuration Subsystem
    Config["Configuration Subsystem (JSON & env vars)"]:::config
    Config -.-> ClientCLI
    Config -.-> NetMgrClient
    Config -.-> NetMgrServer
    Config -.-> ServerCLI

    %% Click Events
    click ClientCLI "https://github.com/karanm6505/huffstream/blob/main/client/client.py"
    click SampleFiles "https://github.com/karanm6505/huffstream/tree/main/client/sending_files/"
    click NetMgrClient "https://github.com/karanm6505/huffstream/blob/main/utils/network_manager.py"
    click NetMgrServer "https://github.com/karanm6505/huffstream/blob/main/utils/network_manager.py"
    click Encoder "https://github.com/karanm6505/huffstream/blob/main/utils/encode_file.py"
    click Decoder "https://github.com/karanm6505/huffstream/blob/main/utils/decode_file.py"
    click CertScript "https://github.com/karanm6505/huffstream/blob/main/generate_certificates.sh"
    click TestSSL "https://github.com/karanm6505/huffstream/blob/main/test_ssl_connection.py"
    click Encoder "https://github.com/karanm6505/huffstream/blob/main/utils/huffman.py"
    click Decoder "https://github.com/karanm6505/huffstream/blob/main/utils/huffman.py"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef server fill:#90EE90,stroke:#333,stroke-width:1px
    classDef utils fill:#FFA500,stroke:#333,stroke-width:1px
    classDef network fill:#D3D3D3,stroke:#666,stroke-width:1px,stroke-dasharray: 5 5
    classDef scripts fill:#CCCCCC,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
    classDef config fill:#EEEEEE,stroke:#333,stroke-width:1px
    classDef storage fill:#D3D3D3,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
