# changlan/kytan architecture

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

- Interactive diagram: https://gitdiagram.com/changlan/kytan
- Repository: https://github.com/changlan/kytan

## Overview

##### Project type and purpose
- Kytan is a Rust-based, peer-to-peer VPN tool offering server and client modes. It ships as a single CLI binary that creates a virtual network interface (TUN/TAP), encapsulates/decapsulates IP packets, and sends them over UDP sockets with optional encryption and NAT traversal.

##### File structure
- Cargo.toml, .travis.yml, README.md, LICENSE at top level.
- src/main.rs: entry point, kicks off either server or client.
- src/cli.rs: command-line parsing (modes, flags, logging).
- src/device.rs: TUN/TAP interface setup and read/write.
- src/network.rs: UDP socket creation, peer management, NAT punch-through or hole-punching logic.
- src/packet.rs: packet framing, encryption/decryption, ordering, sequence numbers.
- src/utils.rs: logging, config loading, error handling, common helpers.

##### Read README for additional architecture clues
- Two operational modes: server (listens for peers, sets up NAT masquerade) and client (connects to server).
- Uses iptables externally for NAT on the server.
- Minimal config and multi-platform support.

a. Main components:
- CLI layer (cli.rs)
- Core engine
– Device Manager (device.rs)
– Packet Processor (packet.rs)
– Network Engine (network.rs)
- Utility services (utils.rs)
- OS Kernel/Network Stack (TUN/TAP driver, UDP stack, iptables)
b. Relationships & interactions:
- User invokes CLI → CLI parses flags/mode → instantiates Core engine
- Core engine starts Device Manager → creates a virtual interface (e.g., /dev/net/tun)
- Device Manager ↔ Packet Processor: reads raw IP packets from TUN, passes to Packet Processor for encapsulation
- Packet Processor ↔ Network Engine: SEND: encrypts and frames data, hands to Network Engine to send over UDP. RECEIVE: Network Engine receives UDP datagrams, passes to Packet Processor for decryption/decapsulation.
- Packet Processor → Device Manager: writes decapsulated IP packets back into the TUN device → OS Kernel routes them to the local network stack or other applications.
- Utilities provide logging, config, error handling to all modules.
- Server mode adds iptables/NAT setup step (external to the binary, shown as configuration on the OS).
c. Architectural patterns and principles:
- Modular separation of concerns: CLI, device abstraction, networking, and packet processing in distinct modules.
- Single binary with runtime mode selection (server vs. client).
- Synchronous main loop or async reactor pattern (depending on implementation) for multiplexing device I/O and socket I/O.
- Extensibility points: you could swap out the encryption algorithm in packet.rs or support additional transports in network.rs.
d. Key technologies/frameworks:
- Rust language and Cargo build system
- TUN/TAP virtual network interface (OS kernel driver)
- UDP sockets for P2P transport
- (Planned) iptables commands for NAT on Linux
- Logging via the standard Rust log facade (controlled by RUST_LOG)

##### Final reminders
- Be granular: break out device, packet, and network handling instead of lumping them together.
- Integration with the OS kernel (virtual interface, NAT) as a first-class element.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Project Files
    subgraph "Project Files"
        CFG["Cargo.toml"]:::config
        CI[".travis.yml"]:::config
        DOC["README.md"]:::config
        LIC["LICENSE"]:::config
    end

    %% Entry Point
    Main["Entry Point<br/>(main.rs)"]:::user

    %% User-land Modules
    subgraph "User-land Modules"
        CLI["CLI Layer<br/>(cli.rs)"]:::user
        subgraph "Core Engine"
            DM["Device Manager<br/>(device.rs)"]:::user
            PP["Packet Processor<br/>(packet.rs)"]:::user
            NE["Network Engine<br/>(network.rs)"]:::user
        end
        UTIL["Utilities<br/>(utils.rs)"]:::util
    end

    %% OS / Kernel Layer
    subgraph "OS / Kernel"
        TUN["TUN/TAP Driver"]:::os
        UDP["UDP Stack"]:::os
        IPT["iptables NAT<br/>(server mode)"]:::os
    end

    %% Control Flow
    Main -->|"initialize"| CLI
    CLI -->|"launch mode"| DM

    %% Data Flow Forward
    DM -->|"IP frames"| PP
    PP -->|"encrypted payload"| NE
    NE -->|"UDP datagram"| UDP

    %% Data Flow Reverse
    UDP -->|"UDP datagram"| NE
    NE -->|"decrypt & decapsulate"| PP
    PP -->|"IP frames"| DM

    %% Utility Dependencies
    UTIL -.-> CLI
    UTIL -.-> DM
    UTIL -.-> PP
    UTIL -.-> NE

    %% External NAT
    IPT -.->|"configures"| UDP

    %% Click Events
    click Main "https://github.com/changlan/kytan/blob/master/src/main.rs"
    click CLI "https://github.com/changlan/kytan/blob/master/src/cli.rs"
    click DM "https://github.com/changlan/kytan/blob/master/src/device.rs"
    click PP "https://github.com/changlan/kytan/blob/master/src/packet.rs"
    click NE "https://github.com/changlan/kytan/blob/master/src/network.rs"
    click UTIL "https://github.com/changlan/kytan/blob/master/src/utils.rs"
    click CFG "https://github.com/changlan/kytan/blob/master/Cargo.toml"
    click CI "https://github.com/changlan/kytan/blob/master/.travis.yml"
    click DOC "https://github.com/changlan/kytan/blob/master/README.md"
    click LIC "https://github.com/changlan/kytan/tree/master/LICENSE"

    %% Styles
    classDef user fill:#add8e6,stroke:#333,stroke-width:1px;
    classDef util fill:#90ee90,stroke:#333,stroke-width:1px;
    classDef os fill:#d3d3d3,stroke:#333,stroke-width:1px;
    classDef config fill:#ffe4b5,stroke:#333,stroke-width:1px;
```
