Architecture

Architecture

A conceptual tour of how Player Club Private VPN is put together, and where to find each piece in the repository. For current build/test status of each block, see Project Status.

Diagram

Target architecture. The NAT / TUN / FEC / split-tunnel blocks and the IPC layer are built; Game Detection and the Config / Profile Store are planned and shown here for the intended shape.

flowchart TB
    subgraph UI["Frontend — Tauri WebView (React + TS + Tailwind)"]
        Nav["Sidebar + Breadcrumb"]
        Diag["Diagnostics<br/>Topology · Spectrum · Packet Logs"]
        Set["Settings<br/>Basic / Expert · JSON Profiles"]
        Pers["Themes (x6) + i18n"]
    end

    subgraph Core["Backend — Rust Engine (src-tauri)"]
        CMD["Tauri Command / Event Layer (IPC)"]
        NAT["NAT Traversal"]
        TUN["TUN/TAP Adapter Mgmt"]
        FEC["Forward Error Correction"]
        SPLIT["Split Tunneling"]
        GAME["Game Detection"]
        CFG["Config / Profile Store"]
    end

    OS[("OS Network Stack<br/>Virtual Adapter")]
    Peers(("Remote Peers"))

    UI <-->|commands / events| CMD
    CMD --> NAT
    CMD --> TUN
    CMD --> FEC
    CMD --> SPLIT
    CMD --> GAME
    CMD --> CFG
    TUN <--> OS
    NAT <-->|UDP hole punching| Peers
    FEC <--> Peers
    SPLIT --> OS

Loading

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 Project Status entries under "Elevation helper" for exactly how much of that migration is complete.

Project structure

.
├── .github/
│   ├── workflows/                # CI (Windows release builds)
│   ├── ISSUE_TEMPLATE/           # Bug report / feature request forms
│   └── DISCUSSION_TEMPLATE/      # Discussion category forms
├── src-tauri/                    # Rust / Tauri backend (the networking engine)
│   ├── src/
│   │   ├── engine/                # The engine
│   │   │   ├── crypto/            # X25519 identity, Noise IK, AEAD session, replay
│   │   │   ├── transport/         # Shared UDP socket, framing, keepalive/RTT
│   │   │   ├── nat/               # STUN + candidate gathering
│   │   │   ├── signaling/         # Paste-robust PCPV1 offer/answer blobs
│   │   │   ├── tun/               # Virtual adapter (Wintun) + elevation
│   │   │   ├── dataplane/         # Adapter ⇄ async driver bridge
│   │   │   ├── fec/               # Forward Error Correction (XOR parity)
│   │   │   ├── split_tunnel/      # Egress / ingress packet policy
│   │   │   ├── telemetry/         # Metrics, packet log, sink seam
│   │   │   ├── pipeline.rs        # Handshake → steady-state session driver
│   │   │   └── connection.rs      # Peer link lifecycle
│   │   └── commands/              # Tauri IPC command handlers + event bridge
│   ├── capabilities/              # Tauri permission capabilities
│   ├── resources/wintun/          # Bundled signed wintun.dll (see THIRD-PARTY-NOTICES)
│   └── icons/                     # App icons
├── src/                           # React + TypeScript frontend
│   ├── components/                # Layout shell, diagnostics, settings, primitives
│   ├── pages/                     # Routed views
│   ├── hooks/                     # React hooks
│   ├── stores/                    # Client state (zustand)
│   ├── lib/                       # Frontend utilities / IPC wrappers
│   ├── styles/                    # Global + Tailwind styles
│   ├── themes/                    # Predefined visual themes
│   ├── i18n/locales/              # Translations
│   └── types/                     # Shared TypeScript types
├── public/                        # Static public files
├── README.md                      # Overview + quick start
├── CHANGELOG.md                   # Versioned change history
├── LICENSE                        # Proprietary licence + disclaimer — read before use
├── TERMS_OF_SERVICE.md            # Terms governing use of the software & project
├── PRIVACY_POLICY.md              # What data the app does/doesn't handle
├── SECURITY.md                    # Vulnerability reporting policy
└── THIRD-PARTY-NOTICES.md         # Bundled/third-party component licences