# jdtsillas/udpvpn architecture

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

- Interactive diagram: https://gitdiagram.com/jdtsillas/udpvpn
- Repository: https://github.com/jdtsillas/udpvpn

## Overview

UDP VPN Tunnel is a Linux command-line program that forwards IP packets between a TUN device and a remote UDP endpoint. The workflow parses local and remote endpoints, optionally loads symmetric encryption and signing keys, opens the tunnel and UDP sockets, then asynchronously relays packets in both directions. When encryption is enabled, outgoing packets are AES-encrypted and HMAC-signed; incoming packets are signature-checked and decrypted before delivery to TUN. The excerpts show the relay and cryptographic operations; other details are based on README statements.

Main entry points: [`udpvpn.cpp`](https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp) (Tunnel server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration"]
  node_options["CLI options<br/>[udpvpn.cpp]"]
  node_endpoint_parse["Endpoint parsing<br/>[udpvpn.cpp]"]
  node_key_loading["Key loading<br/>[udpvpn.cpp]"]
end

subgraph group_relay["Packet relay"]
  node_server["Tunnel server<br/>[udpvpn.cpp]"]
  node_tun_device["TUN device"]
  node_tun_receive["TUN receive<br/>[udpvpn.cpp]"]
  node_udp_send["UDP send<br/>[udpvpn.cpp]"]
  node_udp_receive["UDP receive<br/>[udpvpn.cpp]"]
  node_tun_write["TUN delivery<br/>[udpvpn.cpp]"]
end

subgraph group_security["Optional security"]
  node_crypto["Encrypt and sign<br/>[udpvpn.cpp]"]
  node_verify_decrypt["Verify and decrypt<br/>[udpvpn.cpp]"]
end

node_operator(("Operator"))
node_udp_peer(("Remote UDP peer"))
node_key_file["Key file"]

node_operator -->|"sets options"| node_options
node_options -->|"parses endpoints"| node_endpoint_parse
node_options -->|"loads keys"| node_key_loading
node_key_file -->|"provides keys"| node_key_loading
node_options -->|"configures"| node_server
node_server -->|"opens"| node_tun_device
node_server -->|"configures endpoint"| node_udp_peer
node_server -->|"starts reads"| node_tun_receive
node_server -->|"starts reads"| node_udp_receive
node_tun_receive -->|"encrypts and signs"| node_crypto
node_tun_receive -->|"sends packets"| node_udp_send
node_udp_send -->|"sends datagrams"| node_udp_peer
node_udp_receive -->|"checks and decrypts"| node_verify_decrypt
node_udp_receive -->|"writes packets"| node_tun_write
node_tun_write -->|"delivers packets"| node_tun_device

click node_options "https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp"
click node_endpoint_parse "https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp"
click node_key_loading "https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp"
click node_server "https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp"
click node_tun_receive "https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp"
click node_udp_send "https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp"
click node_udp_receive "https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp"
click node_tun_write "https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp"
click node_crypto "https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp"
click node_verify_decrypt "https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp"

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_options,node_endpoint_parse,node_key_loading toneBlue
class node_server,node_tun_device,node_tun_receive,node_udp_send,node_udp_receive,node_tun_write toneAmber
class node_crypto,node_verify_decrypt toneMint
class node_operator,node_udp_peer,node_key_file toneIndigo
```

## Components

### Configuration

- [CLI options](https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp): `udpvpn.cpp`
- [Endpoint parsing](https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp): `udpvpn.cpp`
- [Key loading](https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp): `udpvpn.cpp`

### Packet relay

- [Tunnel server](https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp): `udpvpn.cpp`
- **TUN device**
- [TUN receive](https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp): `udpvpn.cpp`
- [UDP send](https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp): `udpvpn.cpp`
- [UDP receive](https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp): `udpvpn.cpp`
- [TUN delivery](https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp): `udpvpn.cpp`

### Optional security

- [Encrypt and sign](https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp): `udpvpn.cpp`
- [Verify and decrypt](https://github.com/jdtsillas/udpvpn/blob/master/udpvpn.cpp): `udpvpn.cpp`

### Other components

- **Operator**
- **Remote UDP peer**
- **Key file**

## Connections

- Operator → CLI options: sets options (evidence: `README.md`)
- CLI options → Endpoint parsing: parses endpoints (evidence: `udpvpn.cpp`)
- CLI options → Key loading: loads keys (evidence: `udpvpn.cpp`)
- Key file → Key loading: provides keys (evidence: `README.md`)
- CLI options → Tunnel server: configures (evidence: `udpvpn.cpp`)
- Tunnel server → TUN device: opens (evidence: `README.md`)
- Tunnel server → Remote UDP peer: configures endpoint (evidence: `README.md`)
- Tunnel server → TUN receive: starts reads (evidence: `udpvpn.cpp`)
- Tunnel server → UDP receive: starts reads (evidence: `udpvpn.cpp`)
- TUN receive → Encrypt and sign: encrypts and signs (evidence: `udpvpn.cpp`)
- TUN receive → UDP send: sends packets (evidence: `udpvpn.cpp`)
- UDP send → Remote UDP peer: sends datagrams (evidence: `udpvpn.cpp`)
- UDP receive → Verify and decrypt: checks and decrypts (evidence: `udpvpn.cpp`)
- UDP receive → TUN delivery: writes packets (evidence: `udpvpn.cpp`)
- TUN delivery → TUN device: delivers packets (evidence: `udpvpn.cpp`)