# markqvist/reticulum architecture

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

- Interactive diagram: https://gitdiagram.com/markqvist/reticulum
- Repository: https://github.com/markqvist/reticulum

## Overview

─────────────────────────────────────────────
##### Project Type and Purpose
─────────────────────────────────────────────
- Project Type: Reticulum is a complete networking stack implemented in Python. It’s designed for building local and wide‑area networks using diverse physical media.
- Purpose: It provides end‑to‑end encryption, multi‑hop routing based on cryptographic principles, and a flexible, modular interface system. The system is intended for constructing resilient, decentralized networks without traditional IP dependencies.

─────────────────────────────────────────────
##### File Structure and Main Code Components
─────────────────────────────────────────────
- Core Library Directories:
- “RNS”: This is the heart of the network stack that contains modules such as:
- Cryptography modules (located in RNS/Cryptography): Implements AES, Ed25519, HKDF, HMAC, and other primitives. It also includes both OpenSSL‑backed and pure‑Python implementations.
- Network interfaces (RNS/Interfaces): Contains a variety of interface types (TCP, UDP, serial, Android, pipe, I2P) – these are the pluggable modules that allow Reticulum to communicate over different physical media.
- Core Networking Modules: Files like Buffer.py, Channel.py, Destination.py, Identity.py, Link.py, Packet.py, Resolver.py, Resource.py, Reticulum.py, and Transport.py represent various layers of the network stack (from link and packet management up to transport and routing).
- Utilities (RNS/Utilities): Contains helper modules such as rncp, rnid, rnprobe, rnpath, rnstatus, and rnx which are also exposed as command-line tools.
- “CRNS”: Likely represents an earlier or complementary core library (possibly encapsulating lower‑level network routines) with its own __init__.py file.
- Examples & Tests:
- “Examples”: Simple demonstration scripts (e.g., Announce.py, Echo.py, Filetransfer.py) showing how to use the networking stack.
- “tests”: Contains test suites for verifying functionality of channels, hashes, identity, links, and configuration.
- Documentation & Community Files:
- “docs” and README, Roadmap, Changelog, and Contributing files provide further context on the architecture and usage.

─────────────────────────────────────────────
##### Main Components
─────────────────────────────────────────────
A. Application/Utility Layer
– Reticulum Daemon (rnsd): Runs the networking system as a service.
– Command‑line utilities (rnstatus, rnpath, rnprobe, rnid, rncp, rnx) that interact with the core stack to manage and diagnose the network.

B. Core Networking Stack (RNS)
– Packet, Channel, and Buffer: Responsible for data segmentation, reliable delivery, and sequencing (ensuring unforgeable delivery acknowledgements and sequential packet handling).
– Link and Transport Management: Modules that establish and manage physical or virtual links between nodes and handle multi‑hop routing.
– Identity and Routing: Components that manage globally unique addressing, routing, and identity keys.

C. Cryptography Subsystem (RNS/Cryptography and sub‑directories)
– Cryptographic Primitives: Implements symmetric (AES‑128 in CBC mode, PKCS7 padding) and asymmetric algorithms (Ed25519 signatures, X25519 ECDH), as well as hashing functions (SHA‑256, SHA‑512).
– Dual Implementations: Shows dependency on external PyCA/cryptography/OpenSSL if available, with an internal pure‑Python fallback.

D. Interface Modules Layer (RNS/Interfaces)
– Multiple interface implementations (e.g., TCPInterface, UDPInterface, KISSInterface, SerialInterface, Android interfaces, I2PInterface, LocalInterface) that abstract the actual connectivity over diverse physical and virtual mediums.

E. External Dependencies
– Third‑party libraries: PyCA/cryptography, pyserial, and others which gate the functionality (e.g., faster cryptographic operations with OpenSSL vs. fallback on slower pure‑Python variants).
– System configuration files and build scripts (e.g., setup.py, Makefile, GitHub workflows) support testing and continuous integration.

─────────────────────────────────────────────
##### Relationships and Interactions Between Components
─────────────────────────────────────────────
- The Application/Utility Layer (rnsd and CLI utilities) calls into the Core Networking Stack.
- The Core Stack leverages:
- The Cryptography Subsystem to secure network communications (signing, encryption/decryption, token generation).
- The Interface Layer to send and receive data over various physical media.
- Data and commands typically flow as follows:
1. User initiates a command via a utility (e.g., rnstatus).
2. The utility interfaces with the core (RNS modules) to interpret routing, identity, and packet information.
3. The core interacts with one or more interface modules for actual data transmission or reception.
4. During these operations, cryptographic modules secure data and verify communications.
5. Underneath, lower-level packet handling (channel, link, buffer management) provides reliable data transfer.
- Command/control flow (utilities → core stack).
- Data flow between the core stack and the interfaces.
- Security dependency flow (from core stack to cryptographic modules).
- External dependency linkages (showing where PyCA/cryptography and pyserial integrate).

─────────────────────────────────────────────
##### Architectural Patterns and Principles
─────────────────────────────────────────────
- Layered Architecture: Separate layers for interfaces, core network logic, and security.
- Modularity: Pluggable interface modules that allow users to extend or customize functionality easily without rewriting core logic.
- Separation of Concerns: Distinct categorizations for networking, identity management, transport, and encryption.
- Redundancy & Fallback: Dual cryptographic implementations (external libraries versus pure‑Python), ensuring flexibility in deployment across different systems.

─────────────────────────────────────────────

─────────────────────────────────────────────
- Start at the top with the “Application/Utility Layer” (rnsd, rnstatus, etc.) that manages and interacts with the entire system.
- Underneath, have a large container for the “Core Networking Stack (RNS)” that further divides into:
- Packet/Channel/Buffer Management, Link/Transport Handling, and Identity/Routing Management.
- Finally, annotate dependencies on external libraries (PyCA/cryptography, pyserial), configuration and build scripts, and testing/doc components.
- That each component is:
- Clearly labeled.

─────────────────────────────────────────────
Conclusion
─────────────────────────────────────────────

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Application/Utility Layer
    subgraph "Application/Utility Layer"
        ud1["Reticulum Daemon (rnsd)"]:::utility
        ud2["CLI: rnstatus"]:::utility
        ud3["CLI: rnpath"]:::utility
        ud4["CLI: rnprobe"]:::utility
        ud5["CLI: rnid"]:::utility
        ud6["CLI: rncp"]:::utility
        ud7["CLI: rnx"]:::utility
    end

    %% Core Networking Stack
    subgraph "Core Networking Stack"
        %% Packet/Channel/Buffer Management
        subgraph "Packet/Channel/Buffer Management"
            n1["Packet Module"]:::core
            n2["Channel Module"]:::core
            n3["Buffer Module"]:::core
        end
        %% Link and Transport Management
        subgraph "Link/Transport Management"
            n4["Link Module"]:::core
            n5["Transport Module"]:::core
        end
        %% Identity and Routing Management
        subgraph "Identity/Routing Management"
            n6["Identity Module"]:::core
            n7["Destination Module"]:::core
            n8["Resolver Module"]:::core
        end
    end

    %% Cryptography Module
    subgraph "Cryptography Module"
        c1["AES"]:::crypto
        c2["Ed25519"]:::crypto
        c3["HKDF"]:::crypto
        c4["HMAC"]:::crypto
        c5["SHA256"]:::crypto
        c6["SHA512"]:::crypto
        c7["PKCS7"]:::crypto
        c8["Token"]:::crypto
        c9["Provider"]:::crypto
    end

    %% Interface Modules Layer
    subgraph "Interface Modules"
        i1["TCP Interface"]:::interface
        i2["UDP Interface"]:::interface
        i3["Serial Interface"]:::interface
        i4["KISS Interface"]:::interface
        i5["I2P Interface"]:::interface
        i6["Local Interface"]:::interface
        i7["Android Interface"]:::interface
    end

    %% Complementary/Legacy Core Library
    subgraph "Complementary/Legacy Core Library"
        l1["CRNS Library"]:::core
        l2["__init__.py"]:::core
    end

    %% External Dependencies & Build Scripts
    subgraph "External Dependencies & Build"
        e1["PyCA/cryptography"]:::external
        e2["pyserial"]:::external
        e3["setup.py"]:::external
        e4["Makefile"]:::external
    end

    %%-------------------------
    %% Connections between layers

    %% Application Layer calls into Core Networking Stack
    ud1 -->|"calls_core"| n1
    ud1 -->|"calls_core"| n4
    ud1 -->|"calls_core"| n6

    %% Core Networking Stack uses Cryptography Module
    n1 -->|"secures"| c1
    n4 -->|"secures"| c4
    n6 -->|"secures"| c7

    %% Core Networking Stack interfaces with Interface Modules
    n4 -->|"interfaces_with"| i1
    n4 -->|"interfaces_with"| i2
    n4 -->|"interfaces_with"| i3
    n6 -->|"interfaces_with"| i7

    %% Legacy support connection (CRNS supports core routines)
    l1 ---|"legacy_support"| n1
    l1 ---|"legacy_support"| n4
    l1 ---|"legacy_support"| n6

    %% Cryptography Module dependency on external cryptography library
    c1 -->|"depends_on"| e1
    c2 -->|"depends_on"| e1

    %% Interface Module dependency on pyserial for serial communication
    i3 -->|"depends_on"| e2

    %% Build/configuration link from Application to build scripts
    ud1 ---|"configured_by"| e3
    ud1 ---|"configured_by"| e4

    %%-------------------------
    %% Styling
    classDef utility fill:#f9e79f,stroke:#b9770e,stroke-width:2px;
    classDef core fill:#aed6f1,stroke:#2e86c1,stroke-width:2px;
    classDef crypto fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef interface fill:#abebc6,stroke:#28b463,stroke-width:2px;
    classDef external fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;

    %%-------------------------
    %% Click Events for Application/Utility Layer
    click ud1 "https://github.com/markqvist/reticulum/blob/master/RNS/Utilities/rnsd.py"
    click ud2 "https://github.com/markqvist/reticulum/blob/master/RNS/Utilities/rnstatus.py"
    click ud3 "https://github.com/markqvist/reticulum/blob/master/RNS/Utilities/rnpath.py"
    click ud4 "https://github.com/markqvist/reticulum/blob/master/RNS/Utilities/rnprobe.py"
    click ud5 "https://github.com/markqvist/reticulum/blob/master/RNS/Utilities/rnid.py"
    click ud6 "https://github.com/markqvist/reticulum/blob/master/RNS/Utilities/rncp.py"
    click ud7 "https://github.com/markqvist/reticulum/blob/master/RNS/Utilities/rnx.py"

    %% Click Events for Core Networking Stack
    click n1 "https://github.com/markqvist/reticulum/blob/master/RNS/Packet.py"
    click n2 "https://github.com/markqvist/reticulum/blob/master/RNS/Channel.py"
    click n3 "https://github.com/markqvist/reticulum/blob/master/RNS/Buffer.py"
    click n4 "https://github.com/markqvist/reticulum/blob/master/RNS/Link.py"
    click n5 "https://github.com/markqvist/reticulum/blob/master/RNS/Transport.py"
    click n6 "https://github.com/markqvist/reticulum/blob/master/RNS/Identity.py"
    click n7 "https://github.com/markqvist/reticulum/blob/master/RNS/Destination.py"
    click n8 "https://github.com/markqvist/reticulum/blob/master/RNS/Resolver.py"

    %% Click Events for Cryptography Module
    click c1 "https://github.com/markqvist/reticulum/blob/master/RNS/Cryptography/AES.py"
    click c2 "https://github.com/markqvist/reticulum/blob/master/RNS/Cryptography/Ed25519.py"
    click c3 "https://github.com/markqvist/reticulum/blob/master/RNS/Cryptography/HKDF.py"
    click c4 "https://github.com/markqvist/reticulum/blob/master/RNS/Cryptography/HMAC.py"
    click c5 "https://github.com/markqvist/reticulum/blob/master/RNS/Cryptography/SHA256.py"
    click c6 "https://github.com/markqvist/reticulum/blob/master/RNS/Cryptography/SHA512.py"
    click c7 "https://github.com/markqvist/reticulum/blob/master/RNS/Cryptography/PKCS7.py"
    click c8 "https://github.com/markqvist/reticulum/blob/master/RNS/Cryptography/Token.py"
    click c9 "https://github.com/markqvist/reticulum/blob/master/RNS/Cryptography/Provider.py"

    %% Click Events for Interface Modules Layer
    click i1 "https://github.com/markqvist/reticulum/blob/master/RNS/Interfaces/TCPInterface.py"
    click i2 "https://github.com/markqvist/reticulum/blob/master/RNS/Interfaces/UDPInterface.py"
    click i3 "https://github.com/markqvist/reticulum/blob/master/RNS/Interfaces/SerialInterface.py"
    click i4 "https://github.com/markqvist/reticulum/blob/master/RNS/Interfaces/KISSInterface.py"
    click i5 "https://github.com/markqvist/reticulum/blob/master/RNS/Interfaces/I2PInterface.py"
    click i6 "https://github.com/markqvist/reticulum/blob/master/RNS/Interfaces/LocalInterface.py"
    click i7 "https://github.com/markqvist/reticulum/tree/master/RNS/Interfaces/Android"

    %% Click Events for Complementary/Legacy Core Library
    click l1 "https://github.com/markqvist/reticulum/tree/master/CRNS"
    click l2 "https://github.com/markqvist/reticulum/blob/master/CRNS/__init__.py"
```
