# wireguard/wireguard-windows architecture

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

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

## Overview

##### Project Type and Purpose
- Type: Native Windows desktop client (system utility) for managing WireGuard VPN tunnels.
- Purpose: Provide a user-friendly GUI + service/driver integration layer around the WireGuardNT kernel module, including installer, updater, and localization support.

##### File Structure
Top-level modules:
- conf: configuration parsing, registry/file writing
- driver: Go wrappers for loading/unloading the WireGuardNT driver and in-memory driver injection (“memmod”)
- elevate: privilege-elevation helpers (SeShellExecute, DoAs)
- embeddable-dll-service: a C# demo service embedding the WireGuard driver
- installer: MSI/WiX setup, custom actions, fetcher in C
- manager: Windows Service control, IPC server/client to UI/processes
- services: core service bootstrapping and error handling
- tunnel: tunnel setup, interface watching, MTU monitoring, firewall integration
- ui: Go-based desktop GUI (tray, dialogs, pages, syntax highlight)
- updater: auto-update logic (Signify, MSI runner, HTTP via WinHTTP syscalls)
- version: version number, user agent, certificate bundling
- l18n/locales: localization loader and JSON message bundles
- main.go: application entry point

##### Extract Key Insights from README
- It wraps the official WireGuardNT driver.
- It ships an installer and standalone MSIs.
- It’s meant for end users and enterprise deployment.
- The building and deployment docs are in docs/*.md.

##### Main Components & Their Relationships
A. UI Layer (ui/)
­– Sends user commands (Add/Remove/Up/Down tunnel)

B. IPC & Service Manager (manager/, services/)
­– UI ↔ Manager via named-pipe or socket IPC (ipc_client.go ↔ ipc_server.go)
­– Manager runs as Windows service (service.go) and orchestrates underlying modules

C. Driver Loader (driver/)
­– Loads/unloads the WireGuardNT kernel driver via Service Control Manager or in-memory injection (memmod)
­– Uses low-level syscalls on Windows architectures (32/64/ARM)

D. Tunnel Configuration (tunnel/)
­– Establishes network interface (winipcfg)
­– Applies IP addr, routes, firewall rules (tunnel/firewall/)
­– Monitors MTU & interface changes

E. Configuration Store (conf/)
­– Parses .conf files, registry fallbacks, writes configuration to disk/registry
­– Watches for file changes (storewatcher)

F. Updater (updater/)
­– Checks version manifest, downloads new MSI via WinHTTP, verifies signatures (Signify), launches MSI installer

G. Installer (installer/)
­– MSI/WiX definitions, custom C actions for fetcher
­– Runs at install time, not part of runtime process

H. Localization (l18n/ + locales/)
­– Loads JSON message bundles, falls back to English

I. Version & Logging (version/, ringlogger/)
­– Embeds version metadata, user-agent, certificate for signing
­– ringlogger captures debug output, dump functionality

J. Embeddable DLL Service (embeddable-dll-service/)
­– A C# demo showing how to embed the WireGuard driver and control it via a .NET service
­– Optional demo only, separate process

##### Architectural Patterns & Design Principles
- Layered Modularity – Each top-level folder isolates a concern (UI, IPC, driver, tunnel, config, update).
- Service Boundary – UI runs as user process; core driver control runs as elevated Windows service via IPC.
- Adapter Pattern – driver/memmod adapts Go into low-level Windows syscalls.
- Watcher/Observer – conf/storewatcher listens for config changes.
- Plugin-style Localization – l18n dynamically loads translations.
- CI/CD Ready – installer scripts and tests (e.g., dpapi_windows_test.go, tunnel/firewall/types_windows_test.go).

##### Essential Elements
- Component names and directory references (e.g., manager/, driver/)
- Flow of control and data (UI commands → service → driver/tunnel)
- Config read/write path (conf/ → filesystem/registry)
- Update channel (updater/ → WinHTTP → MSI runner)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Space Layer
    subgraph "User Space"
        UI["UI (Go)"]:::frontend
        Localization["Localization Bundles"]:::localization
    end

    %% Elevated Service Layer
    subgraph "Elevated Service"
        IPCService["IPC Server/Service (Go)"]:::ipc
        DriverLoader["Driver Loader"]:::driver
        TunnelManager["Tunnel Manager"]:::tunnel
        ConfigStore["Configuration Store"]:::config
        VersionLogging["Version & Logging"]:::version
    end

    %% Deployment Tools
    subgraph "Deployment Tools"
        UpdaterComp["Updater"]:::updater
        InstallerComp["Installer"]:::installer
    end

    %% External Systems
    InternetCloud["Internet (Update Server)"]:::external
    WindowsKernel["Windows Kernel"]:::external
    OSNetworking["OS Networking Stack"]:::external
    FileReg["Filesystem/Registry"]:::external
    MSIInstaller["MSI Installer"]:::external

    %% Embeddable Demo
    Embeddable["Embeddable DLL Service"]:::embeddable

    %% Connections
    UI -->|"commands"| IPCService
    IPCService -->|"load/unload driver"| DriverLoader
    IPCService -->|"manage tunnels"| TunnelManager
    IPCService -->|"read/write config"| ConfigStore
    IPCService -->|"log events"| VersionLogging

    DriverLoader -->|"syscalls"| WindowsKernel
    TunnelManager -->|"configure interface"| OSNetworking
    TunnelManager -->|"apply firewall rules"| OSNetworking
    ConfigStore -->|"persist"| FileReg

    UpdaterComp -->|"download MSI"| InternetCloud
    UpdaterComp -->|"launch installer"| MSIInstaller
    MSIInstaller --> InstallerComp
    InstallerComp -->|"install service"| IPCService

    Localization --> UI
    VersionLogging --> IPCService

    Embeddable -.-> DriverLoader

    %% Click Events
    click UI "https://github.com/wireguard/wireguard-windows/tree/master/ui/"
    click Localization "https://github.com/wireguard/wireguard-windows/tree/master/l18n/"
    click IPCService "https://github.com/wireguard/wireguard-windows/tree/master/manager/"
    click DriverLoader "https://github.com/wireguard/wireguard-windows/tree/master/driver/"
    click TunnelManager "https://github.com/wireguard/wireguard-windows/tree/master/tunnel/"
    click ConfigStore "https://github.com/wireguard/wireguard-windows/tree/master/conf/"
    click VersionLogging "https://github.com/wireguard/wireguard-windows/tree/master/version/"
    click UpdaterComp "https://github.com/wireguard/wireguard-windows/tree/master/updater/"
    click InstallerComp "https://github.com/wireguard/wireguard-windows/tree/master/installer/"
    click Embeddable "https://github.com/wireguard/wireguard-windows/tree/master/embeddable-dll-service/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef ipc fill:#FFA500,stroke:#000,stroke-width:1px
    classDef driver fill:#A9A9A9,stroke:#000,stroke-width:1px
    classDef tunnel fill:#90EE90,stroke:#000,stroke-width:1px
    classDef config fill:#FFFF66,stroke:#000,stroke-width:1px
    classDef updater fill:#FF6347,stroke:#000,stroke-width:1px
    classDef installer fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef localization fill:#20B2AA,stroke:#000,stroke-width:1px
    classDef version fill:#A52A2A,stroke:#000,stroke-width:1px
    classDef embeddable fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef external fill:#FFFFFF,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
```
