How wireguard/wireguard-android works
Project type and purpose
• This is a full-stack Android application (“ui” module) plus a companion tunnel library (“tunnel” module) that manages WireGuard VPN tunnels.
• The “tunnel” library wraps both a kernel-mode implementation (via wireguard-tools) and a userspace implementation (libwg-go), exposing a uniform Java API to the UI.
File structure
• Top-level Gradle build with two subprojects:
• tunnel – pure Java/Kotlin plus JNI wrapper and native tools under tunnel/tools.
• ui – Android app (Kotlin) with Activities, Fragments, ViewModels, data binding, resources.
• Key directories:
• tunnel/src/main/java/com/wireguard/backend – Backend.java interface, GoBackend, WgQuickBackend, Tunnel, Statistics.
• tunnel/src/main/java/com/wireguard/config – Config parsing/model classes.
• tunnel/tools – C/C++ sources building libwg-go, ndk-compat, and wireguard-tools.
• ui/src/main/java/com/wireguard/android – Application entry point, BootShutdownReceiver, QuickTileService.
• ui/src/main/java/com/wireguard/android/configStore – ConfigStore interface and FileConfigStore.
• ui/src/main/java/com/wireguard/android/viewmodel – MVVM proxies (ConfigProxy, TunnelManager, etc.).
Important architectural patterns & design principles
• MVVM & data binding in the UI module (Activities ↔ ViewModels ↔ data binding adapters).
• Clean separation of UI vs. tunnel management via TunnelManager and the Backend interface.
• Abstraction of native vs. shell backends using a common Java interface.
• JNI + SharedLibraryLoader for loading libwg-go; RootShell for invoking wg-quick commands.
• Config persistence abstracted behind ConfigStore.
Main components and their relationships
[UI Layer]
• Activities & Fragments
• ViewModels (ConfigProxy, TunnelManager)
• DataBinding layer
↕ invokes
[ConfigStore]
• FileConfigStore (reads/writes .conf files on disk)
↕ hands Config objects to
[Tunnel Library]
• Config model & parser (com.wireguard.config)
• Crypto utilities (Curve25519, KeyPair)
• Backend interface (start/stop/status)
– GoBackend (.so via JNI & libwg-go)
– WgQuickBackend (shell commands via RootShell + wireguard-tools)
↕ interacts with
[Android OS / Kernel]
• VpnService API (Android-built VPN stub)
• Kernel module (if present) or fallbacks
• System shell (requires root for wg-quick)