init

docs/architecture.md

@@ -0,0 +1,141 @@
+# 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.