Architecture

Architecture

A conceptual tour of how Player Club Private VPN is put together. For the canonical diagram and the current build/test status of each block, see the README's Architecture and Project Status sections — this page explains the why, not just the what.

Two halves: engine and shell

The Rust engine (src-tauri/src/engine/) owns everything that touches the network or the OS: cryptography, NAT traversal, the virtual adapter, FEC, and split-tunnel policy. It runs on Tauri's async runtime and exposes state and events to the frontend over Tauri's IPC command/event bridge — the frontend never touches sockets or the adapter directly.

The React frontend (src/) is presentation and control: the app shell, Diagnostics readouts, Settings, and the Network/Minecraft pages. It reflects engine state and issues commands; it holds no networking logic of its own.

The connection lifecycle, end to end

1. Identity — on first run, the engine generates an X25519 key pair, stored locally (see Legal & Privacy).
2. Signaling — two peers exchange an Offer/Answer blob containing a public key and NAT-traversal candidates. This can happen manually (paste the blob anywhere you trust), or be relayed automatically through a peer-hosted signaling server when using a named Virtual Network.
3. NAT traversal (hole-punching) — both sides fan out UDP packets to each other's candidate addresses; the first exchange that lands nominates the winning path. This doubles as the transport-layer handshake.
4. Handshake — a Noise IK handshake authenticates both sides using their X25519 identities and derives an AEAD session with anti-replay protection.
5. Data plane — the local virtual adapter (Wintun, Windows) hands IP packets to the engine, which applies split-tunnel policy, optionally adds Forward Error Correction (Reed-Solomon) redundancy, encrypts, and sends them over the authenticated session — and the reverse on receive.
6. Live telemetry — RTT, jitter, loss, throughput, and FEC/policy counters stream to the Diagnostics view throughout.

Why no relay/TURN and no site-to-site sharing

Both are deliberately out of scope for the same reason: they require infrastructure or trust assumptions beyond "two consenting peers with direct UDP reachability," which is the model this project commits to. A host behind a NAT without port forwarding, or a peer whose network can't be traversed directly, is a known limitation rather than a bug — see the README's Project Status table for the current itemised state of that tradeoff.

Elevation and the helper process

Creating a Wintun adapter requires Administrator privileges on Windows. Rather than relaunching the entire application elevated, the engine is moving toward a small elevated helper process that owns just the adapter lifecycle and talks to the main (unelevated) process over a named pipe. See the engine::tun::windows module and the README's Project Status entries under "Elevation helper" for exactly how much of that migration is complete.