# wireguard/wireguard-android architecture

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

- Interactive diagram: https://gitdiagram.com/wireguard/wireguard-android
- Repository: https://github.com/wireguard/wireguard-android

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "UI Module"
        class UIMod ui
        Activity["Activities"]:::ui
        click Activity "https://github.com/wireguard/wireguard-android/tree/master/ui/src/main/java/com/wireguard/android/activity"
        Fragment["Fragments"]:::ui
        click Fragment "https://github.com/wireguard/wireguard-android/tree/master/ui/src/main/java/com/wireguard/android/fragment"
        ViewModel["ViewModels"]:::ui
        click ViewModel "https://github.com/wireguard/wireguard-android/tree/master/ui/src/main/java/com/wireguard/android/viewmodel"
        Binding["DataBinding Adapters"]:::ui
        click Binding "https://github.com/wireguard/wireguard-android/blob/master/ui/src/main/java/com/wireguard/android/databinding/BindingAdapters.kt"
        App["Application Entry Point"]:::ui
        click App "https://github.com/wireguard/wireguard-android/blob/master/ui/src/main/java/com/wireguard/android/Application.kt"
        Boot["Boot/Shutdown Receiver"]:::ui
        click Boot "https://github.com/wireguard/wireguard-android/blob/master/ui/src/main/java/com/wireguard/android/BootShutdownReceiver.kt"
        Tile["QuickTileService"]:::ui
        click Tile "https://github.com/wireguard/wireguard-android/blob/master/ui/src/main/java/com/wireguard/android/QuickTileService.kt"
        TunnelManager["TunnelManager"]:::ui
        click TunnelManager "https://github.com/wireguard/wireguard-android/blob/master/ui/src/main/java/com/wireguard/android/model/TunnelManager.kt"
    end

    subgraph "ConfigStore"
        ConfigStore["ConfigStore Interface"]:::ui
        click ConfigStore "https://github.com/wireguard/wireguard-android/blob/master/ui/src/main/java/com/wireguard/android/configStore/ConfigStore.kt"
        FileConfig["FileConfigStore"]:::ui
        click FileConfig "https://github.com/wireguard/wireguard-android/blob/master/ui/src/main/java/com/wireguard/android/configStore/FileConfigStore.kt"
    end

    subgraph "Tunnel Library"
        ConfigModel["Config Parser & Model"]:::lib
        click ConfigModel "https://github.com/wireguard/wireguard-android/tree/master/tunnel/src/main/java/com/wireguard/config"
        Crypto["Crypto Utilities"]:::lib
        click Crypto "https://github.com/wireguard/wireguard-android/tree/master/tunnel/src/main/java/com/wireguard/crypto"
        BackendInt["Backend Interface"]:::lib
        click BackendInt "https://github.com/wireguard/wireguard-android/blob/master/tunnel/src/main/java/com/wireguard/android/backend/Backend.java"
        GoBE["GoBackend (JNI)"]:::lib
        click GoBE "https://github.com/wireguard/wireguard-android/blob/master/tunnel/src/main/java/com/wireguard/android/backend/GoBackend.java"
        QuickBE["WgQuickBackend"]:::lib
        click QuickBE "https://github.com/wireguard/wireguard-android/blob/master/tunnel/src/main/java/com/wireguard/android/backend/WgQuickBackend.java"
        TunnelObj["Tunnel"]:::lib
        click TunnelObj "https://github.com/wireguard/wireguard-android/blob/master/tunnel/src/main/java/com/wireguard/android/backend/Tunnel.java"
        Statistics["Statistics"]:::lib
        click Statistics "https://github.com/wireguard/wireguard-android/blob/master/tunnel/src/main/java/com/wireguard/android/backend/Statistics.java"
        SharedLib["SharedLibraryLoader"]:::lib
        click SharedLib "https://github.com/wireguard/wireguard-android/blob/master/tunnel/src/main/java/com/wireguard/android/util/SharedLibraryLoader.java"
        RootShell["RootShell"]:::lib
        click RootShell "https://github.com/wireguard/wireguard-android/blob/master/tunnel/src/main/java/com/wireguard/android/util/RootShell.java"
        ToolsInst["ToolsInstaller"]:::lib
        click ToolsInst "https://github.com/wireguard/wireguard-android/blob/master/tunnel/src/main/java/com/wireguard/android/util/ToolsInstaller.java"
    end

    subgraph "Native Tools"
        libwg["libwg-go"]:::native
        click libwg "https://github.com/wireguard/wireguard-android/tree/master/tunnel/tools/libwg-go"
        ndk["ndk-compat"]:::native
        click ndk "https://github.com/wireguard/wireguard-android/tree/master/tunnel/tools/ndk-compat"
        wgtools["wireguard-tools"]:::native
        click wgtools "https://github.com/wireguard/wireguard-android/tree/master/tunnel/tools/wireguard-tools"
    end

    subgraph "Android OS / Kernel"
        VpnService["VpnService API"]:::os
        SystemShell["System Shell"]:::os
        KernelMod["Kernel Module"]:::os
    end

    Activity --> ViewModel
    Fragment --> ViewModel
    ViewModel -->|"reads/writes .conf"| ConfigStore
    ConfigStore --> FileConfig
    FileConfig -->|"parses .conf"| ConfigModel
    ConfigModel --> TunnelObj
    ConfigModel --> Statistics
    ViewModel --> TunnelManager
    TunnelManager --> BackendInt
    BackendInt -->|"JNI call"| GoBE
    BackendInt -->|"exec wg-quick"| QuickBE
    GoBE --> SharedLib
    SharedLib --> libwg
    QuickBE --> RootShell
    RootShell --> wgtools
    GoBE -->|"VpnService API"| VpnService
    QuickBE --> SystemShell
    VpnService --> KernelMod
    SystemShell --> KernelMod

    classDef ui fill:#CCE5FF,stroke:#3399FF
    classDef lib fill:#D4EDDA,stroke:#28A745
    classDef native fill:#FFF3CD,stroke:#FFC107
    classDef os fill:#E2E3E5,stroke:#6C757D
```
