# gutschke/wgrtc architecture

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

- Interactive diagram: https://gitdiagram.com/gutschke/wgrtc
- Repository: https://github.com/gutschke/wgrtc

## Overview

Wgrtc is an Android WireGuard manager for joining or hosting tunnels, including NAT traversal, phone-to-phone wormhole pairing, and multiple concurrent joiner tunnels. The principal flow runs from Android UI through the ViewModel into tunnel configuration and a VPN service; signaling discovers and refreshes peer endpoints, while native bridge code carries tunnel traffic. The README also describes a Linux daemon, but its runtime source is absent from this tree, so it is not mapped. Some connections below reflect explicit documentation or source-index references; unsampled internals limit detail.

Main entry points: [`android/app/src/main/kotlin/com/gutschke/wgrtc/WgrtcViewModel.kt`](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/WgrtcViewModel.kt) (Tunnel workflow), [`android/app/src/main/kotlin/com/gutschke/wgrtc/data/WgBridgeNative.kt`](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/WgBridgeNative.kt) (Native bridge API), [`android/app/src/main/kotlin/com/gutschke/wgrtc/data/WormholeHostController.kt`](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/WormholeHostController.kt) (Wormhole host), [`android/app/src/main/kotlin/com/gutschke/wgrtc/data/WormholeJoinController.kt`](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/WormholeJoinController.kt) (Wormhole join)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Android app"]
  node_activity["App navigation<br/>[MainActivity.kt]"]
  node_viewmodel["Tunnel workflow<br/>[WgrtcViewModel.kt]"]
  node_appboot["App lifecycle<br/>[WgrtcApp.kt]"]
  node_tunnel["Tunnel model<br/>[Tunnel.kt]"]
  node_registry["Tunnel state"]
end

subgraph group_pairing["Pairing and signaling"]
  node_enroll["Enrollment client<br/>[EnrollClient.kt]"]
  node_wormhost["Wormhole host"]
  node_wormjoin["Wormhole join"]
  node_wormcode["Pairing codes<br/>[WormholeCode.kt]"]
  node_roam["Roam recovery<br/>[RoamController.kt]"]
end

subgraph group_tunnel["Tunnel runtime"]
  node_vpnconfig["VPN configuration<br/>[JoinerVpnConfig.kt]"]
  node_joincontroller["Joiner orchestration"]
  node_joinservice["Shared VPN service"]
  node_singlevpn["Single VPN service"]
  node_hostvpn["Host VPN service"]
  node_stack["Userspace stack"]
end

subgraph group_network["Networking features"]
  node_dns["DNS proxy<br/>[DnsProxy.kt]"]
  node_dnsservice["DNS listener<br/>[DnsService.kt]"]
end

subgraph group_native["Native bridge"]
  node_nativeapi["Native bridge API<br/>[WgBridgeNative.kt]"]
  node_nativeimpl["Bridge implementation<br/>[api.go]"]
end

node_user(("User"))
node_broker(("Signaling broker"))
node_internet(("Peer network"))

node_user -->|"uses"| node_activity
node_activity -->|"invokes"| node_viewmodel
node_viewmodel -.->|"manages"| node_tunnel
node_viewmodel -.->|"connects"| node_joinservice
node_viewmodel -.->|"connects"| node_singlevpn
node_viewmodel -->|"starts"| node_wormhost
node_viewmodel -->|"starts"| node_wormjoin
node_appboot -.->|"reconciles"| node_registry
node_appboot -.->|"registers listeners"| node_broker
node_wormhost -->|"uses"| node_wormcode
node_wormjoin -->|"uses"| node_wormcode
node_wormhost -.->|"signals"| node_broker
node_wormjoin -.->|"signals"| node_broker
node_enroll -->|"enrolls"| node_broker
node_roam -.->|"races endpoints"| node_internet
node_joinservice -->|"delegates"| node_joincontroller
node_joincontroller -->|"rebuilds"| node_stack
node_joinservice -->|"installs protector"| node_nativeapi
node_singlevpn -->|"applies"| node_vpnconfig
node_singlevpn -.->|"uses"| node_nativeapi
node_hostvpn -->|"protects sockets"| node_nativeapi
node_stack -->|"calls"| node_nativeapi
node_nativeapi -.->|"bridges to"| node_nativeimpl
node_dnsservice -->|"handles queries"| node_dns
node_dnsservice -->|"listens on"| node_stack
node_nativeimpl -.->|"forwards traffic"| node_internet

click node_activity "https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/MainActivity.kt"
click node_viewmodel "https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/WgrtcViewModel.kt"
click node_appboot "https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/WgrtcApp.kt"
click node_tunnel "https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/Tunnel.kt"
click node_registry "https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/TunnelStateRegistry.kt"
click node_enroll "https://github.com/gutschke/wgrtc/blob/main/android/signalling/src/main/kotlin/com/gutschke/wgrtc/signalling/EnrollClient.kt"
click node_wormhost "https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/WormholeHostController.kt"
click node_wormjoin "https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/WormholeJoinController.kt"
click node_wormcode "https://github.com/gutschke/wgrtc/blob/main/android/signalling/src/main/kotlin/com/gutschke/wgrtc/signalling/WormholeCode.kt"
click node_roam "https://github.com/gutschke/wgrtc/blob/main/android/signalling/src/main/kotlin/com/gutschke/wgrtc/signalling/RoamController.kt"
click node_vpnconfig "https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/JoinerVpnConfig.kt"
click node_joincontroller "https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/JoinerNController.kt"
click node_joinservice "https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/service/JoinerNVpnService.kt"
click node_singlevpn "https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/service/JoinerVpnService.kt"
click node_hostvpn "https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/service/HostModeVpnService.kt"
click node_stack "https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/JoinerStackBackend.kt"
click node_dns "https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/DnsProxy.kt"
click node_dnsservice "https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/DnsService.kt"
click node_nativeapi "https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/WgBridgeNative.kt"
click node_nativeimpl "https://github.com/gutschke/wgrtc/blob/main/android/wgbridge_native/api.go"

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_activity,node_viewmodel,node_appboot,node_tunnel,node_registry,node_user toneBlue
class node_enroll,node_wormhost,node_wormjoin,node_wormcode,node_roam toneAmber
class node_vpnconfig,node_joincontroller,node_joinservice,node_singlevpn,node_hostvpn,node_stack toneMint
class node_dns,node_dnsservice toneRose
class node_nativeapi,node_nativeimpl,node_broker,node_internet toneIndigo
```

## Components

### Android app

- [App navigation](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/MainActivity.kt): `android/app/src/main/kotlin/com/gutschke/wgrtc/MainActivity.kt`
- [Tunnel workflow](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/WgrtcViewModel.kt): `android/app/src/main/kotlin/com/gutschke/wgrtc/WgrtcViewModel.kt`
- [App lifecycle](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/WgrtcApp.kt): `android/app/src/main/kotlin/com/gutschke/wgrtc/WgrtcApp.kt`
- [Tunnel model](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/Tunnel.kt): `android/app/src/main/kotlin/com/gutschke/wgrtc/data/Tunnel.kt`
- [Tunnel state](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/TunnelStateRegistry.kt): `android/app/src/main/kotlin/com/gutschke/wgrtc/data/TunnelStateRegistry.kt`

### Pairing and signaling

- [Enrollment client](https://github.com/gutschke/wgrtc/blob/main/android/signalling/src/main/kotlin/com/gutschke/wgrtc/signalling/EnrollClient.kt): `android/signalling/src/main/kotlin/com/gutschke/wgrtc/signalling/EnrollClient.kt`
- [Wormhole host](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/WormholeHostController.kt): `android/app/src/main/kotlin/com/gutschke/wgrtc/data/WormholeHostController.kt`
- [Wormhole join](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/WormholeJoinController.kt): `android/app/src/main/kotlin/com/gutschke/wgrtc/data/WormholeJoinController.kt`
- [Pairing codes](https://github.com/gutschke/wgrtc/blob/main/android/signalling/src/main/kotlin/com/gutschke/wgrtc/signalling/WormholeCode.kt): `android/signalling/src/main/kotlin/com/gutschke/wgrtc/signalling/WormholeCode.kt`
- [Roam recovery](https://github.com/gutschke/wgrtc/blob/main/android/signalling/src/main/kotlin/com/gutschke/wgrtc/signalling/RoamController.kt): `android/signalling/src/main/kotlin/com/gutschke/wgrtc/signalling/RoamController.kt`

### Tunnel runtime

- [VPN configuration](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/JoinerVpnConfig.kt): `android/app/src/main/kotlin/com/gutschke/wgrtc/data/JoinerVpnConfig.kt`
- [Joiner orchestration](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/JoinerNController.kt): `android/app/src/main/kotlin/com/gutschke/wgrtc/data/JoinerNController.kt`
- [Shared VPN service](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/service/JoinerNVpnService.kt): `android/app/src/main/kotlin/com/gutschke/wgrtc/service/JoinerNVpnService.kt`
- [Single VPN service](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/service/JoinerVpnService.kt): `android/app/src/main/kotlin/com/gutschke/wgrtc/service/JoinerVpnService.kt`
- [Host VPN service](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/service/HostModeVpnService.kt): `android/app/src/main/kotlin/com/gutschke/wgrtc/service/HostModeVpnService.kt`
- [Userspace stack](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/JoinerStackBackend.kt): `android/app/src/main/kotlin/com/gutschke/wgrtc/data/JoinerStackBackend.kt`

### Networking features

- [DNS proxy](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/DnsProxy.kt): `android/app/src/main/kotlin/com/gutschke/wgrtc/data/DnsProxy.kt`
- [DNS listener](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/DnsService.kt): `android/app/src/main/kotlin/com/gutschke/wgrtc/data/DnsService.kt`

### Native bridge

- [Native bridge API](https://github.com/gutschke/wgrtc/blob/main/android/app/src/main/kotlin/com/gutschke/wgrtc/data/WgBridgeNative.kt): `android/app/src/main/kotlin/com/gutschke/wgrtc/data/WgBridgeNative.kt`
- [Bridge implementation](https://github.com/gutschke/wgrtc/blob/main/android/wgbridge_native/api.go): `android/wgbridge_native/api.go`

### Other components

- **User**
- **Signaling broker**
- **Peer network**

## Connections

- User → App navigation: uses (evidence: `android/app/src/main/kotlin/com/gutschke/wgrtc/MainActivity.kt`)
- App navigation → Tunnel workflow: invokes (evidence: `android/app/src/main/kotlin/com/gutschke/wgrtc/MainActivity.kt`)
- Tunnel workflow → Tunnel model: manages (evidence: `android/app/src/main/kotlin/com/gutschke/wgrtc/WgrtcViewModel.kt`)
- Tunnel workflow → Shared VPN service: connects
- Tunnel workflow → Single VPN service: connects
- Tunnel workflow → Wormhole host: starts (evidence: `android/app/src/main/kotlin/com/gutschke/wgrtc/MainActivity.kt`)
- Tunnel workflow → Wormhole join: starts (evidence: `android/app/src/main/kotlin/com/gutschke/wgrtc/MainActivity.kt`)
- App lifecycle → Tunnel state: reconciles
- App lifecycle → Signaling broker: registers listeners
- Wormhole host → Pairing codes: uses (evidence: `android/app/src/main/kotlin/com/gutschke/wgrtc/data/WormholeHostController.kt`)
- Wormhole join → Pairing codes: uses (evidence: `android/app/src/main/kotlin/com/gutschke/wgrtc/data/WormholeJoinController.kt`)
- Wormhole host → Signaling broker: signals
- Wormhole join → Signaling broker: signals
- Enrollment client → Signaling broker: enrolls (evidence: `android/signalling/src/main/kotlin/com/gutschke/wgrtc/signalling/EnrollClient.kt`)
- Roam recovery → Peer network: races endpoints
- Shared VPN service → Joiner orchestration: delegates (evidence: `android/app/src/main/kotlin/com/gutschke/wgrtc/service/JoinerNVpnService.kt`)
- Joiner orchestration → Userspace stack: rebuilds (evidence: `android/app/src/main/kotlin/com/gutschke/wgrtc/data/JoinerNController.kt`)
- Shared VPN service → Native bridge API: installs protector (evidence: `android/app/src/main/kotlin/com/gutschke/wgrtc/service/JoinerNVpnService.kt`)
- Single VPN service → VPN configuration: applies (evidence: `android/app/src/main/kotlin/com/gutschke/wgrtc/service/JoinerVpnService.kt`)
- Single VPN service → Native bridge API: uses (evidence: `android/app/src/main/kotlin/com/gutschke/wgrtc/service/JoinerVpnService.kt`)
- Host VPN service → Native bridge API: protects sockets (evidence: `android/app/src/main/kotlin/com/gutschke/wgrtc/service/HostModeVpnService.kt`)
- Userspace stack → Native bridge API: calls (evidence: `android/app/src/main/kotlin/com/gutschke/wgrtc/data/JoinerStackBackend.kt`)
- Native bridge API → Bridge implementation: bridges to
- DNS listener → DNS proxy: handles queries (evidence: `android/app/src/main/kotlin/com/gutschke/wgrtc/data/DnsService.kt`)
- DNS listener → Userspace stack: listens on (evidence: `android/app/src/main/kotlin/com/gutschke/wgrtc/data/DnsService.kt`)
- Bridge implementation → Peer network: forwards traffic
