# VPN Share Architecture

## Product Contract

VPN Share shares an Android phone's active VPN with nearby devices through an
encrypted application tunnel. The receiving device runs a small companion client
that installs or opens its own virtual network interface and routes traffic to
the phone automatically.

The phone app does not replace the user's VPN provider. It preserves the active
VPN app and forwards client traffic through Android's default network routing.

## Non-Negotiable Platform Constraints

- No root and Android 8+ means no direct manipulation of system NAT, tethering
  routing tables, or hotspot iptables.
- Only one Android app can be prepared as the active `VpnService` owner at a
  time. The gateway app therefore cannot run a phone-side `VpnService` while
  WireGuard, OpenVPN, Clash, V2Ray, or another VPN is active.
- Android `LocalOnlyHotspot` is local-only and does not provide Internet. VPN
  Share uses it only as a local transport for the encrypted tunnel.
- `VpnService.protect()` must not be used for forwarded gateway sockets because
  protected sockets bypass VPN routing.

## Component Diagram

```mermaid
flowchart TB
  subgraph AndroidPhone[Android phone]
    UI[Compose app UI]
    FG[Gateway foreground service]
    DET[VpnDetector]
    DISC[Discovery: QR, mDNS, USB]
    FFI[Rust FFI adapter]
    ENG[vpnshare-core]
    NAT[Userspace TCP/UDP NAT]
    DNS[DNS forwarder/cache]
    MTU[MTU/MSS manager]
  end

  subgraph Clients[Receiving devices]
    DC[Desktop client]
    AC[Android client VpnService]
    IC[iOS Network Extension]
  end

  DC -->|USB/Wi-Fi/hotspot VSHP| FG
  AC -->|Wi-Fi/hotspot VSHP| FG
  IC -->|Wi-Fi/hotspot VSHP| FG
  UI --> FG
  FG --> DET
  FG --> DISC
  FG --> FFI
  FFI --> ENG
  ENG --> NAT
  ENG --> DNS
  ENG --> MTU
  NAT -->|Android sockets| VPN[Existing active VPN app]
  DNS -->|Android resolver/network DNS| VPN
  VPN --> Internet[Internet]
```

## Data Flow

```mermaid
flowchart LR
  App[Client application traffic] --> TUN[Client virtual NIC]
  TUN --> Packetizer[Client VSHP packetizer]
  Packetizer --> Crypto[Noise session encryption]
  Crypto --> Transport[USB/Wi-Fi/hotspot transport]
  Transport --> Gateway[Android gateway service]
  Gateway --> Engine[Rust engine]
  Engine --> NAT[NAT / DNS / flow control]
  NAT --> Socket[Android TCP/UDP sockets]
  Socket --> ActiveVpn[Existing active VPN]
  ActiveVpn --> Internet
```

## Main Sequences

### USB-First Pairing

```mermaid
sequenceDiagram
  participant User
  participant Phone
  participant Desktop
  participant Engine

  User->>Phone: Tap Share
  Phone->>Phone: Start foreground gateway
  Phone->>Phone: Verify active VPN network
  Desktop->>Phone: Open USB accessory channel
  Desktop->>Phone: HELLO with client public key
  Phone->>User: Show pairing code and device name
  User->>Phone: Approve
  Phone->>Engine: Create peer lease
  Phone->>Desktop: AUTH + CONFIG
  Desktop->>Desktop: Configure virtual NIC/routes/DNS
  Desktop->>Phone: IP_PACKET frames
  Phone->>Internet: Forward via active VPN
```

### Reconnection

```mermaid
sequenceDiagram
  Client->>Gateway: PING session_id, counters
  Gateway--xClient: Transport interruption
  Client->>Gateway: RESUME session_id, ticket
  Gateway->>Gateway: Validate ticket and peer policy
  Gateway->>Client: CONFIG delta
  Client->>Gateway: Continue packet frames
```

## Android Domain Model

- `GatewaySession`: active share session with transport set, peer leases, VPN
  status, and byte counters.
- `PeerDevice`: trusted receiving device with public key, platform, label,
  first seen, last seen, and revocation status.
- `PairingRequest`: short-lived untrusted request created by USB, QR, or mDNS.
- `TransportEndpoint`: USB accessory, LAN UDP/TCP, or local-only-hotspot path.
- `TunnelLease`: client virtual IPs, DNS gateway, MTU, route set, and expiry.

## Runtime Policy

- Gateway starts only from user action and remains foreground while sharing.
- Gateway shows a persistent notification with connected peer count and a stop
  action.
- If no active VPN network is detected, the app can still start local pairing
  but marks Internet sharing unavailable until the VPN appears.
- Forwarded traffic never leaves the device through a protected or underlying
  non-VPN socket unless the user explicitly enables a future advanced bypass
  mode.

## Future Desktop Architecture

The Rust protocol/core crates are shared by Android gateway and desktop clients.
Desktop-specific modules only provide virtual NIC, installer, service manager,
tray UI, and OS network configuration.