# khagendran/kn-sock architecture

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

- Interactive diagram: https://gitdiagram.com/khagendran/kn-sock
- Repository: https://github.com/khagendran/kn-sock

## Overview

##### Project type and purpose
- kn-sock is an open-source Python socket programming toolkit.
- It provides synchronous/asynchronous TCP and UDP communication, JSON-over-socket, file transfer, helper utilities, decorators, and a CLI.

##### File structure
- Top-level modules in `easy_socket/` implement core functionality:
- `tcp.py`, `udp.py`, `json_socket.py`, `file_transfer.py`
- `cli.py` exposes commands for end users
- `decorators.py`, `utils.py`, `errors.py` support logging, retries, validation, error handling
- `examples/` contains usage scripts for each feature.
- `setup.py` and `requirements.txt` define packaging and dependencies.

##### README for additional insights
- Confirms features (sync/async TCP & UDP, JSON, file transfer, multi-client support).
- CLI commands map directly to functions in `cli.py`.
- Decorators and utils are designed as extension points.

##### Main components and relationships
a. Components:
- CLI layer (`easy_socket/cli.py`)
- Core modules: `tcp`, `udp`, `json_socket`, `file_transfer`
- Utilities layer: `decorators`, `utils`, `errors`
- Network (sockets over TCP/UDP)
- File system (for file transfer)
- External environment: User scripts or automated clients/servers
b. Interactions:
- CLI invokes core modules based on command
- Core modules use Python’s `socket` API or `asyncio` primitives
- Core modules call into `decorators` and `utils` for logging, retries, JSON validation, progress display, chunking
- File transfer module reads/writes files via `utils.chunked_file_reader` and `print_progress`
- Errors propagate via custom exceptions in `errors.py`
c. Architectural patterns and principles:
- Layering: CLI → Core → Utilities → System APIs
- Dependency injection: Handlers passed to server-start functions
- Extensibility: Decorators wrap user handlers; utils are standalone helpers
d. Key technologies and frameworks:
- Python standard library: `socket`, `asyncio`, `argparse`
- Packaging: `setuptools`, PyPI
- Threading/multi-client support in synchronous servers

##### Detailed capture of essential elements
- Break out synchronous vs. asynchronous paths under TCP/UDP.
- JSON socket as a wrapper over TCP that serializes/deserializes.
- Decorator chain around user-provided handlers (e.g., logging → retry → time measurement → JSON validation).
- Example scripts and how they map to the modules (optional layer for examples).

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "CLI Layer"
        CLI["CLI"]:::cli
    end

    subgraph "Core Modules"
        TCP["TCP Server/Client"]:::core
        UDP["UDP Server/Client"]:::core
        JSONS["JSON-over-Socket"]:::core
        FT["File Transfer"]:::core
    end

    subgraph "Utilities Layer"
        DEC["Decorators"]:::util
        UTIL["Utils"]:::util
        ERR["Errors/Exceptions"]:::util
    end

    NETWORK["Network (TCP/UDP)"]:::infra
    FS["File System"]:::storage

    subgraph "Example Scripts"
        E1["TCP Example (Client)"] 
        E2["TCP Example (Server)"]
        E3["UDP Example (Client)"]
        E4["UDP Example (Server)"]
        E5["JSON Socket Example (Client)"]
        E6["JSON Socket Example (Server)"]
        E7["File Transfer Example (Sender)"]
        E8["File Transfer Example (Server)"]
    end

    CLI -->|"invokes"| TCP
    CLI -->|"invokes"| UDP
    CLI -->|"invokes"| JSONS
    CLI -->|"invokes"| FT

    TCP -->|"sends/receives"| NETWORK
    UDP -->|"sends/receives"| NETWORK
    JSONS -->|"wraps over"| TCP
    FT -->|"read/write"| FS

    TCP -->|"uses"| DEC
    UDP -->|"uses"| DEC
    JSONS -->|"uses"| DEC
    FT -->|"uses"| DEC

    TCP -->|"uses"| UTIL
    UDP -->|"uses"| UTIL
    JSONS -->|"uses"| UTIL
    FT -->|"uses"| UTIL

    TCP -->|"raises"| ERR
    UDP -->|"raises"| ERR
    JSONS -->|"raises"| ERR
    FT -->|"raises"| ERR

    E1 -->|"example of"| TCP
    E2 -->|"example of"| TCP
    E3 -->|"example of"| UDP
    E4 -->|"example of"| UDP
    E5 -->|"example of"| JSONS
    E6 -->|"example of"| JSONS
    E7 -->|"example of"| FT
    E8 -->|"example of"| FT

    click CLI "https://github.com/khagendran/kn-sock/blob/main/easy_socket/cli.py"
    click TCP "https://github.com/khagendran/kn-sock/blob/main/easy_socket/tcp.py"
    click UDP "https://github.com/khagendran/kn-sock/blob/main/easy_socket/udp.py"
    click JSONS "https://github.com/khagendran/kn-sock/blob/main/easy_socket/json_socket.py"
    click FT "https://github.com/khagendran/kn-sock/blob/main/easy_socket/file_transfer.py"
    click DEC "https://github.com/khagendran/kn-sock/blob/main/easy_socket/decorators.py"
    click UTIL "https://github.com/khagendran/kn-sock/blob/main/easy_socket/utils.py"
    click ERR "https://github.com/khagendran/kn-sock/blob/main/easy_socket/errors.py"

    click E1 "https://github.com/khagendran/kn-sock/blob/main/examples/tcp_client.py"
    click E2 "https://github.com/khagendran/kn-sock/blob/main/examples/tcp_server.py"
    click E3 "https://github.com/khagendran/kn-sock/blob/main/examples/udp_client.py"
    click E4 "https://github.com/khagendran/kn-sock/blob/main/examples/udp_server.py"
    click E5 "https://github.com/khagendran/kn-sock/blob/main/examples/json_client.py"
    click E6 "https://github.com/khagendran/kn-sock/blob/main/examples/json_server.py"
    click E7 "https://github.com/khagendran/kn-sock/blob/main/examples/file_sender.py"
    click E8 "https://github.com/khagendran/kn-sock/blob/main/examples/file_server.py"

    classDef core fill:#add8e6,stroke:#000
    classDef util fill:#90ee90,stroke:#000
    classDef cli fill:#9370db,stroke:#000
    classDef infra fill:#e0e0e0,stroke:#000,stroke-dasharray: 5 5
    classDef storage fill:#ffe4b5,stroke:#000,stroke-dasharray: 5 5
```
