# nafell/echelon-server architecture

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

- Interactive diagram: https://gitdiagram.com/nafell/echelon-server
- Repository: https://github.com/nafell/echelon-server

## Overview

##### Project type and purpose
- This is a Rust‑based implementation of a lightweight, reliable data‑transfer protocol (NRP) running over UDP.
- It provides a library/CLI that can act as a client or server, handling handshake, sequencing, acknowledgements, retransmissions, and connection teardown.

##### File structure
- Cargo.toml / Cargo.lock – defines a single Rust crate.
- src/main.rs – the executable’s entry point (parses command‑line args, spawns a client or server).
- src/protocol.rs – the core protocol engine (packet definitions, state machine, timers, send/receive logic).

##### README for architectural insights
- Core features: 1‑RTT handshake, adaptive retransmission (Jacobson’s RTT/RTO), sequence‑number ordering, checksums, exponential backoff.
- Execution model: asynchronous I/O + multi‑threading (send/receive loops, timer tasks).
- Configurable parameters (initial_rtt, min/max RTO, window size, etc.).

##### Main components
- Application / CLI layer – initializes ProtocolEngine and I/O threads.
- ProtocolEngine – maintains connection state (Closed, Connecting, Connected, Disconnecting).
- PacketFormatter – builds/parses the 16‑byte header + payload.
- RetransmissionManager – stores sent packets, schedules RTO timers, applies exponential backoff.
- ReceiveBuffer – holds out‑of‑order Data packets.
- TimerManager – drives RTO timers and connection timeouts.
- UDP Socket Abstraction – binds to a local port, sends/receives raw UDP datagrams.
- Peer (remote NRP instance) – the other endpoint over UDP.

##### Relationships and data flow
- The CLI feeds application data into ProtocolEngine.
- ProtocolEngine calls PacketFormatter → constructs Packet → hands off to UDP Socket.
- UDP Socket → Network → remote UDP Socket → remote ProtocolEngine.
- On receipt, UDP Socket → ProtocolEngine → ReceiverBuffer or ack generation.
- ProtocolEngine → RetransmissionManager & TimerManager to track in‑flight packets and timeouts.
- TimerManager → triggers retransmit events back into ProtocolEngine.

##### Architectural patterns and design principles
- Event‑driven state machine (Connection states and packet‑type handlers).
- Layered separation: Application / Protocol logic / Transport (UDP) / Network.
- Concurrency: send loop, receive loop, timer loop (can be threads or async tasks).
- Configurability via ConnectionConfig struct injected into ProtocolEngine.

##### Relevant technologies / libraries
- Rust async runtime (e.g., tokio or async‑std) for non‑blocking I/O.
- Standard library UDP sockets (std::net::UdpSocket) or tokio::net.
- Crossbeam or std threads for timer management (if not using async timers).

##### Detail advice
- Timers and state transitions explicitly (e.g., “RTO timer expires → ProtocolEngine.retransmit()”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Systems"
        App["Application / CLI layer"]:::external
        Peer["Remote Peer"]:::external
        Network["Network"]:::external
    end

    subgraph "Utility Modules"
        Config["ConnectionConfig"]:::utility
        Formatter["PacketFormatter"]:::utility
        CargoToml["Cargo.toml"]:::utility
        CargoLock["Cargo.lock"]:::utility
        Readme["README.md"]:::utility
    end

    subgraph "Core Protocol Logic"
        PEC["ProtocolEngine"]:::core
        RM["RetransmissionManager"]:::core
        RB["ReceiveBuffer"]:::core
        TM["TimerManager"]:::core
    end

    subgraph "Transport Layer"
        UDPSocket["UDP Socket Abstraction"]:::transport
    end

    App -->|"start"| PEC
    Config -->|"injected"| PEC
    PEC -->|"format packet"| Formatter
    Formatter -->|"build packet"| UDPSocket
    UDPSocket -->|"send datagram"| Network
    Network -->|"deliver"| Peer
    Peer -->|"send datagram"| Network
    Network -->|"receive"| UDPSocket
    UDPSocket -->|"raw packet"| PEC
    PEC -->|"buffer packet"| RB
    PEC -->|"track packets"| RM
    PEC -->|"set timers"| TM
    TM -->|"timeout event"| PEC
    RB -->|"deliver data"| App

    click App "https://github.com/nafell/echelon-server/blob/main/src/main.rs"
    click PEC "https://github.com/nafell/echelon-server/blob/main/src/protocol.rs"
    click Formatter "https://github.com/nafell/echelon-server/blob/main/src/protocol.rs"
    click RM "https://github.com/nafell/echelon-server/blob/main/src/protocol.rs"
    click RB "https://github.com/nafell/echelon-server/blob/main/src/protocol.rs"
    click TM "https://github.com/nafell/echelon-server/blob/main/src/protocol.rs"
    click UDPSocket "https://github.com/nafell/echelon-server/blob/main/src/protocol.rs"
    click Config "https://github.com/nafell/echelon-server/blob/main/src/protocol.rs"
    click CargoToml "https://github.com/nafell/echelon-server/blob/main/Cargo.toml"
    click CargoLock "https://github.com/nafell/echelon-server/blob/main/Cargo.lock"
    click Readme "https://github.com/nafell/echelon-server/blob/main/README.md"

    classDef core fill:#d4f7c5,stroke:#333
    classDef utility fill:#e2e2e2,stroke:#333
    classDef transport fill:#c5e4f7,stroke:#333
    classDef external fill:#f7d4c5,stroke:#333
```
