# lelloman/rns-rs architecture

> Architecture diagram of the GitHub repository lelloman/rns-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lelloman/rns-rs
- Repository: https://github.com/lelloman/rns-rs

## Overview

rns-rs is a Rust implementation of the Reticulum networking stack, with node runtimes and user-facing tools layered over its protocol and cryptography crates. A typical workflow is to start a node, connect it through a configured interface, and let transport routing deliver packets; applications can then use links and resource transfers. The workspace also provides administration, programmable hooks, Git-over-Reticulum, VPN tunneling, and embedded-device support. The README documents these capabilities; sampled source confirms selected transport, link, hole-punch, hook, Git, server, and Android behavior, so unsampled subsystem wiring is shown only where documented.

Main entry points: [`rns-net/src/node.rs`](https://github.com/lelloman/rns-rs/blob/master/rns-net/src/node.rs) (Network node and driver), [`rns-core/src/lib.rs`](https://github.com/lelloman/rns-rs/blob/master/rns-core/src/lib.rs) (Protocol and transport), [`rns-server/src/supervisor.rs`](https://github.com/lelloman/rns-rs/blob/master/rns-server/src/supervisor.rs) (Node supervisor), [`rns-hooks/src/manager.rs`](https://github.com/lelloman/rns-rs/blob/master/rns-hooks/src/manager.rs) (Hook runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["Protocol and crypto"]
  node_crypto["Cryptographic primitives<br/>[lib.rs]"]
  node_core["Protocol and transport<br/>[lib.rs]"]
  node_holepunch["NAT hole punching<br/>[engine.rs]"]
end

subgraph group_node["Node runtime"]
  node_net["Network node and driver<br/>[node.rs]"]
  node_interfaces["Network interfaces<br/>[mod.rs]"]
  node_linkmgr["Link and resource manager<br/>[link_manager.rs]"]
  node_persistence[("Node persistence<br/>[storage.rs]")]
end

subgraph group_operations["Operations"]
  node_server["Node supervisor<br/>[supervisor.rs]"]
  node_control["Embedded control plane<br/>[control_plane.rs]"]
  node_ctl["Control CLI and APIs<br/>[main.rs]"]
  node_cli["Node CLI tools<br/>[lib.rs]"]
  node_hooks["Hook runtime<br/>[manager.rs]"]
  node_stats["Statistics hook<br/>[lib.rs]"]
  node_sentinel["Sentinel policy hook<br/>[lib.rs]"]
end

subgraph group_apps["Applications"]
  node_git["Git over Reticulum<br/>[lib.rs]"]
  node_gitserver["Repository server<br/>[server.rs]"]
  node_tunnel["VPN tunnel runtime<br/>[lib.rs]"]
  node_android["Android VPN client<br/>[RntunVpnService.kt]"]
end

subgraph group_devices["Device support"]
  node_esp32["ESP32 LoRa node<br/>[main.rs]"]
end

node_operator(("Node operator"))
node_peers(("Network peers"))
node_client(("Application client"))

node_operator -->|"starts node"| node_server
node_operator -->|"administers"| node_ctl
node_operator -->|"runs commands"| node_cli
node_client -->|"uses repositories"| node_git
node_client -->|"uses VPN"| node_tunnel
node_net -->|"routes packets"| node_core
node_core -->|"uses primitives"| node_crypto
node_net -->|"dispatches traffic"| node_interfaces
node_interfaces -->|"sends and receives"| node_peers
node_net -->|"manages links"| node_linkmgr
node_linkmgr -->|"uses link engines"| node_core
node_net -->|"loads and saves state"| node_persistence
node_core -->|"provides state machine"| node_holepunch
node_server -->|"runs node"| node_net
node_server -->|"hosts"| node_control
node_ctl -->|"controls node"| node_control
node_cli -->|"operates node"| node_net
node_net -.->|"runs hooks"| node_hooks
node_hooks -.->|"loads hook"| node_stats
node_hooks -.->|"loads hook"| node_sentinel
node_git -->|"communicates over"| node_net
node_gitserver -->|"registers link destination"| node_net
node_android -->|"starts native session"| node_tunnel
node_tunnel -->|"uses Reticulum"| node_net
node_esp32 -->|"runs transport"| node_core
node_esp32 -->|"connects LoRa"| node_interfaces

click node_crypto "https://github.com/lelloman/rns-rs/blob/master/rns-crypto/src/lib.rs"
click node_core "https://github.com/lelloman/rns-rs/blob/master/rns-core/src/lib.rs"
click node_holepunch "https://github.com/lelloman/rns-rs/blob/master/rns-core/src/holepunch/engine.rs"
click node_net "https://github.com/lelloman/rns-rs/blob/master/rns-net/src/node.rs"
click node_interfaces "https://github.com/lelloman/rns-rs/blob/master/rns-net/src/interface/mod.rs"
click node_linkmgr "https://github.com/lelloman/rns-rs/blob/master/rns-net/src/common/link_manager.rs"
click node_persistence "https://github.com/lelloman/rns-rs/blob/master/rns-net/src/storage.rs"
click node_server "https://github.com/lelloman/rns-rs/blob/master/rns-server/src/supervisor.rs"
click node_control "https://github.com/lelloman/rns-rs/blob/master/rns-server/src/control_plane.rs"
click node_ctl "https://github.com/lelloman/rns-rs/blob/master/rns-ctl/src/main.rs"
click node_cli "https://github.com/lelloman/rns-rs/blob/master/rns-cli/src/lib.rs"
click node_hooks "https://github.com/lelloman/rns-rs/blob/master/rns-hooks/src/manager.rs"
click node_stats "https://github.com/lelloman/rns-rs/blob/master/rns-stats-hook/src/lib.rs"
click node_sentinel "https://github.com/lelloman/rns-rs/blob/master/rns-sentinel-hook/src/lib.rs"
click node_git "https://github.com/lelloman/rns-rs/blob/master/rns-git/src/lib.rs"
click node_gitserver "https://github.com/lelloman/rns-rs/blob/master/rns-git/src/server.rs"
click node_tunnel "https://github.com/lelloman/rns-rs/blob/master/rns-tun/src/lib.rs"
click node_android "https://github.com/lelloman/rns-rs/blob/master/rns-tun-android/app/src/main/java/com/lelloman/rntun/service/RntunVpnService.kt"
click node_esp32 "https://github.com/lelloman/rns-rs/blob/master/rns-esp32/src/main.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_crypto,node_core,node_holepunch,node_client toneBlue
class node_net,node_interfaces,node_linkmgr,node_persistence toneAmber
class node_server,node_control,node_ctl,node_cli,node_hooks,node_stats,node_sentinel toneMint
class node_git,node_gitserver,node_tunnel,node_android toneRose
class node_esp32,node_operator,node_peers toneIndigo
```

## Components

### Protocol and crypto

- [Cryptographic primitives](https://github.com/lelloman/rns-rs/blob/master/rns-crypto/src/lib.rs): `rns-crypto/src/lib.rs`
- [Protocol and transport](https://github.com/lelloman/rns-rs/blob/master/rns-core/src/lib.rs): `rns-core/src/lib.rs`
- [NAT hole punching](https://github.com/lelloman/rns-rs/blob/master/rns-core/src/holepunch/engine.rs): `rns-core/src/holepunch/engine.rs`

### Node runtime

- [Network node and driver](https://github.com/lelloman/rns-rs/blob/master/rns-net/src/node.rs): `rns-net/src/node.rs`
- [Network interfaces](https://github.com/lelloman/rns-rs/blob/master/rns-net/src/interface/mod.rs): `rns-net/src/interface/mod.rs`
- [Link and resource manager](https://github.com/lelloman/rns-rs/blob/master/rns-net/src/common/link_manager.rs): `rns-net/src/common/link_manager.rs`
- [Node persistence](https://github.com/lelloman/rns-rs/blob/master/rns-net/src/storage.rs): `rns-net/src/storage.rs`

### Operations

- [Node supervisor](https://github.com/lelloman/rns-rs/blob/master/rns-server/src/supervisor.rs): `rns-server/src/supervisor.rs`
- [Embedded control plane](https://github.com/lelloman/rns-rs/blob/master/rns-server/src/control_plane.rs): `rns-server/src/control_plane.rs`
- [Control CLI and APIs](https://github.com/lelloman/rns-rs/blob/master/rns-ctl/src/main.rs): `rns-ctl/src/main.rs`
- [Node CLI tools](https://github.com/lelloman/rns-rs/blob/master/rns-cli/src/lib.rs): `rns-cli/src/lib.rs`
- [Hook runtime](https://github.com/lelloman/rns-rs/blob/master/rns-hooks/src/manager.rs): `rns-hooks/src/manager.rs`
- [Statistics hook](https://github.com/lelloman/rns-rs/blob/master/rns-stats-hook/src/lib.rs): `rns-stats-hook/src/lib.rs`
- [Sentinel policy hook](https://github.com/lelloman/rns-rs/blob/master/rns-sentinel-hook/src/lib.rs): `rns-sentinel-hook/src/lib.rs`

### Applications

- [Git over Reticulum](https://github.com/lelloman/rns-rs/blob/master/rns-git/src/lib.rs): `rns-git/src/lib.rs`
- [Repository server](https://github.com/lelloman/rns-rs/blob/master/rns-git/src/server.rs): `rns-git/src/server.rs`
- [VPN tunnel runtime](https://github.com/lelloman/rns-rs/blob/master/rns-tun/src/lib.rs): `rns-tun/src/lib.rs`
- [Android VPN client](https://github.com/lelloman/rns-rs/blob/master/rns-tun-android/app/src/main/java/com/lelloman/rntun/service/RntunVpnService.kt): `rns-tun-android/app/src/main/java/com/lelloman/rntun/service/RntunVpnService.kt`

### Device support

- [ESP32 LoRa node](https://github.com/lelloman/rns-rs/blob/master/rns-esp32/src/main.rs): `rns-esp32/src/main.rs`

### Other components

- **Node operator**
- **Network peers**
- **Application client**

## Connections

- Node operator → Node supervisor: starts node
- Node operator → Control CLI and APIs: administers
- Node operator → Node CLI tools: runs commands
- Application client → Git over Reticulum: uses repositories
- Application client → VPN tunnel runtime: uses VPN
- Network node and driver → Protocol and transport: routes packets
- Protocol and transport → Cryptographic primitives: uses primitives
- Network node and driver → Network interfaces: dispatches traffic
- Network interfaces → Network peers: sends and receives
- Network node and driver → Link and resource manager: manages links
- Link and resource manager → Protocol and transport: uses link engines
- Network node and driver → Node persistence: loads and saves state
- Protocol and transport → NAT hole punching: provides state machine
- Node supervisor → Network node and driver: runs node
- Node supervisor → Embedded control plane: hosts
- Control CLI and APIs → Embedded control plane: controls node
- Node CLI tools → Network node and driver: operates node
- Network node and driver → Hook runtime: runs hooks
- Hook runtime → Statistics hook: loads hook
- Hook runtime → Sentinel policy hook: loads hook
- Git over Reticulum → Network node and driver: communicates over
- Repository server → Network node and driver: registers link destination
- Android VPN client → VPN tunnel runtime: starts native session
- VPN tunnel runtime → Network node and driver: uses Reticulum
- ESP32 LoRa node → Protocol and transport: runs transport
- ESP32 LoRa node → Network interfaces: connects LoRa