# nonstopble/revpn architecture

> Architecture diagram of the GitHub repository nonstopble/revpn, 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/nonstopble/revpn
- Repository: https://github.com/nonstopble/revpn

## Overview

ReVPN provides interoperable C++ and Python implementations of a TUN-based mesh VPN. The main workflow is to configure a node, connect clients to a rendezvous server, register VPN identities, establish direct UDP peer paths when possible, and otherwise relay traffic through the server; clients bridge packets between TUN and UDP, optionally encrypting tunnel data. The README also documents decentralized token-based peer setup and optional AF_XDP acceleration. Python source excerpts are partial, and the C++ engine is one large source file, so uncertain internal wiring is omitted.

Main entry points: [`engine/meshvpn.cpp`](https://github.com/nonstopble/revpn/blob/main/engine/meshvpn.cpp) (C++ VPN engine), [`python/ReVPN/client.py`](https://github.com/nonstopble/revpn/blob/main/python/ReVPN/client.py) (Python client), [`python/ReVPN/cli.py`](https://github.com/nonstopble/revpn/blob/main/python/ReVPN/cli.py) (CLI and modes), [`python/ReVPN/server.py`](https://github.com/nonstopble/revpn/blob/main/python/ReVPN/server.py) (Python rendezvous)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_pycli["CLI and modes<br/>[cli.py]"]
  node_tui["Interactive menu<br/>[curses_tui.py]"]
  node_presets[("Saved settings<br/>[cli.py]")]
end

subgraph group_pyvpn["Python runtime"]
  node_pyclient["Python client<br/>[client.py]"]
  node_pyserver["Python rendezvous<br/>[server.py]"]
  node_protocol["Wire protocol<br/>[protocol.py]"]
  node_pytun["Python TUN<br/>[tun.py]"]
end

subgraph group_cppvpn["C++ runtime"]
  node_cppengine["C++ VPN engine<br/>[meshvpn.cpp]"]
  node_tun["Virtual network<br/>[meshvpn.cpp]"]
end

subgraph group_accel["Packet acceleration"]
  node_xdp["AF_XDP sockets<br/>[xdp_sock.cpp]"]
  node_bpf["XDP filter<br/>[xdp_kern.c]"]
end

node_user(("VPN operator"))
node_peers(("VPN peers"))
node_udp(("UDP network"))
node_stun(("STUN service"))
node_token(("Peer token exchange"))

node_user -->|"configures"| node_pycli
node_pycli -->|"opens menu"| node_tui
node_pycli -->|"loads and saves"| node_presets
node_pycli -->|"starts server"| node_pyserver
node_pycli -->|"starts client"| node_pyclient
node_pyclient -->|"reads and writes"| node_pytun
node_pyclient -->|"packs and parses"| node_protocol
node_pyserver -->|"packs and parses"| node_protocol
node_pyclient -->|"registers and sends"| node_udp
node_pyserver -->|"receives and relays"| node_udp
node_pyclient -->|"punches and sends"| node_peers
node_udp -->|"delivers packets"| node_pyclient
node_udp -->|"delivers packets"| node_pyserver
node_user -->|"selects mode"| node_cppengine
node_cppengine -->|"bridges packets"| node_tun
node_cppengine -->|"registers and relays"| node_udp
node_cppengine -->|"punches and sends"| node_peers
node_cppengine -.->|"queries address"| node_stun
node_user -->|"exchanges out of band"| node_token
node_token -->|"provides peer setup"| node_cppengine
node_cppengine -.->|"uses optionally"| node_xdp
node_xdp -->|"receives redirected packets"| node_bpf

click node_pycli "https://github.com/nonstopble/revpn/blob/main/python/ReVPN/cli.py"
click node_tui "https://github.com/nonstopble/revpn/blob/main/python/ReVPN/curses_tui.py"
click node_presets "https://github.com/nonstopble/revpn/blob/main/python/ReVPN/cli.py"
click node_pyclient "https://github.com/nonstopble/revpn/blob/main/python/ReVPN/client.py"
click node_pyserver "https://github.com/nonstopble/revpn/blob/main/python/ReVPN/server.py"
click node_protocol "https://github.com/nonstopble/revpn/blob/main/python/ReVPN/protocol.py"
click node_pytun "https://github.com/nonstopble/revpn/blob/main/python/ReVPN/tun.py"
click node_cppengine "https://github.com/nonstopble/revpn/blob/main/engine/meshvpn.cpp"
click node_tun "https://github.com/nonstopble/revpn/blob/main/engine/meshvpn.cpp"
click node_xdp "https://github.com/nonstopble/revpn/blob/main/engine/xdp_sock.cpp"
click node_bpf "https://github.com/nonstopble/revpn/blob/main/engine/xdp_kern.c"

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_pycli,node_tui,node_presets toneBlue
class node_pyclient,node_pyserver,node_protocol,node_pytun toneAmber
class node_cppengine,node_tun toneMint
class node_xdp,node_bpf toneRose
class node_user,node_peers,node_udp,node_stun,node_token toneIndigo
```

## Components

### User entry

- [CLI and modes](https://github.com/nonstopble/revpn/blob/main/python/ReVPN/cli.py): `python/ReVPN/cli.py`
- [Interactive menu](https://github.com/nonstopble/revpn/blob/main/python/ReVPN/curses_tui.py): `python/ReVPN/curses_tui.py`
- [Saved settings](https://github.com/nonstopble/revpn/blob/main/python/ReVPN/cli.py): `python/ReVPN/cli.py`

### Python runtime

- [Python client](https://github.com/nonstopble/revpn/blob/main/python/ReVPN/client.py): `python/ReVPN/client.py`
- [Python rendezvous](https://github.com/nonstopble/revpn/blob/main/python/ReVPN/server.py): `python/ReVPN/server.py`
- [Wire protocol](https://github.com/nonstopble/revpn/blob/main/python/ReVPN/protocol.py): `python/ReVPN/protocol.py`
- [Python TUN](https://github.com/nonstopble/revpn/blob/main/python/ReVPN/tun.py): `python/ReVPN/tun.py`

### C++ runtime

- [C++ VPN engine](https://github.com/nonstopble/revpn/blob/main/engine/meshvpn.cpp): `engine/meshvpn.cpp`
- [Virtual network](https://github.com/nonstopble/revpn/blob/main/engine/meshvpn.cpp): `engine/meshvpn.cpp`

### Packet acceleration

- [AF_XDP sockets](https://github.com/nonstopble/revpn/blob/main/engine/xdp_sock.cpp): `engine/xdp_sock.cpp`
- [XDP filter](https://github.com/nonstopble/revpn/blob/main/engine/xdp_kern.c): `engine/xdp_kern.c`

### Other components

- **VPN operator**
- **VPN peers**
- **UDP network**
- **STUN service**
- **Peer token exchange**

## Connections

- VPN operator → CLI and modes: configures
- CLI and modes → Interactive menu: opens menu
- CLI and modes → Saved settings: loads and saves
- CLI and modes → Python rendezvous: starts server
- CLI and modes → Python client: starts client
- Python client → Python TUN: reads and writes
- Python client → Wire protocol: packs and parses
- Python rendezvous → Wire protocol: packs and parses
- Python client → UDP network: registers and sends
- Python rendezvous → UDP network: receives and relays
- Python client → VPN peers: punches and sends
- UDP network → Python client: delivers packets
- UDP network → Python rendezvous: delivers packets
- VPN operator → C++ VPN engine: selects mode
- C++ VPN engine → Virtual network: bridges packets
- C++ VPN engine → UDP network: registers and relays
- C++ VPN engine → VPN peers: punches and sends
- C++ VPN engine → STUN service: queries address
- VPN operator → Peer token exchange: exchanges out of band
- Peer token exchange → C++ VPN engine: provides peer setup
- C++ VPN engine → AF_XDP sockets: uses optionally
- AF_XDP sockets → XDP filter: receives redirected packets