# netbirdio/wireguard-go architecture

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

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

## Overview

##### Main Components
- Main Application Bootstrapping:
- The entry points are in files like main.go and main_windows.go, which initialize the program.
- TUN Interface Module ("tun" directory):
- This package is responsible for interacting with the network stack by creating and managing tun/tap interfaces. It contains platform-specific implementations (Linux, macOS, Windows, BSD).
- Connection Module ("conn" directory):
- Handles the lower-level transport details of the VPN. It includes OS-specific binding files (bind_std.go, bind_windows.go) and control functions (controlfns, features, sticky handling) that abstract the communication between the WireGuard protocol and the system’s network resources.
- Device Module ("device" directory):
- Manages the higher-level aspects of the VPN interface such as allowed IP management, endpoints, cryptographic handshakes (noise protocol), key management, and state tracking.
- IPC Module ("ipc" directory):
- Provides inter-process communication mechanisms (e.g., via named pipes and uAPI implementations) needed for external configuration or control.
- Auxiliary Utilities:
- Ratellimiter (“ratelimiter”): To manage network traffic rates.
- Replay Prevention (“replay”): Implements anti-replay mechanisms.
- Read/Write Cancellation (“rwcancel”): Provides mechanisms to cancel blocking I/O, important for smooth shutdowns and error recovery.
- Time Handling (“tai64n”): For handling timestamping in a robust way.

##### Relationships and Interactions
- The main application initializes, sets up a TUN interface, and then invokes the connection and device modules.
- The TUN module acts as the bridge between the WireGuard VPN interface and the underlying OS network stack.
- The connection ("conn") module sets up the actual wire guard connection, delegating platform-specific work to the appropriate binding files.
- The device module uses connection primitives to establish cryptographic handshakes (using components like noise-protocol implementations) and to manage routing (allowed IPs, endpoint configurations).
- The IPC module is responsible for accepting runtime configurations (via pipes or sockets) which then affect device and connection states.
- Utility modules (ratelimiter, replay, rwcancel, tai64n) hook into data flows in the device and connection layers to ensure performance, security, and reliability.

##### Architectural Patterns and Design Principles
- Cross-platform Abstraction:
- There are multiple OS-specific files (e.g., *_windows.go, *_linux.go) that illustrate a clear separation of platform-specific logic from common logic.
- Layered/Modular Design:
- The project is split into distinct responsibilities (device management, connection binding, interface configuration, IPC), which makes it easier to maintain and extend.
- Clean Separation Between Control and Data Paths:
- Control (device state, configuration via IPC) is kept separate from the high-throughput data path (TUN interface handling).
- Reusable Helpers/Utilities:
- Utilities like ratelimiter, replay prevention, and read/write cancelation are decoupled, enabling them to be tested and possibly reused in different parts of the system.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Bootstrapping
    subgraph "Bootstrapping"
        M1["main.go"]:::main
        M2["main_windows.go"]:::main
    end

    %% Interface Layer
    subgraph "Interface Layer"
        TUN["TUN Interface\n(Platform-Specific TUN/TAP Driver)"]:::interface
    end

    %% Connection Layer
    subgraph "Connection Layer"
        CON["Connection Manager\n(OS-specific bindings & control)"]:::connection
    end

    %% Device Layer
    subgraph "Device Layer"
        DEV["Device Manager\n(Cryptographic Handshake & Routing)"]:::device
    end

    %% IPC Layer
    subgraph "IPC Layer"
        IPC["IPC Interface\n(Named Pipes & uAPI)"]:::ipc
    end

    %% Utilities
    subgraph "Utilities"
        RL["Rate Limiter"]:::utility
        RP["Replay Prevention"]:::utility
        RWC["RW Cancellation"]:::utility
        TH["Time Handling"]:::utility
    end

    %% Connections from Bootstrapping to Modules
    M1 -->|"initialize"| TUN
    M2 -->|"initialize"| TUN

    M1 -->|"initialize"| CON
    M2 -->|"initialize"| CON

    %% TUN feeds raw traffic to Device Manager
    TUN -->|"raw_data"| DEV

    %% Bidirectional connection between Connection Manager and Device Manager
    CON <-->|"handshake_updates"| DEV

    %% IPC updates configuration in Device Manager and Connection Manager
    IPC -->|"config_update"| DEV
    IPC -->|"config_update"| CON

    %% Utility components as auxiliary supports (dashed connections)
    RL --- DEV
    RL --- CON

    RP --- DEV
    RP --- CON

    RWC --- DEV
    RWC --- CON

    TH --- DEV
    TH --- CON

    %% Click Events
    click M1 "https://github.com/netbirdio/wireguard-go/blob/master//main.go"
    click M2 "https://github.com/netbirdio/wireguard-go/blob/master//main_windows.go"
    click TUN "https://github.com/netbirdio/wireguard-go/tree/master//tun"
    click CON "https://github.com/netbirdio/wireguard-go/tree/master//conn"
    click DEV "https://github.com/netbirdio/wireguard-go/tree/master//device"
    click IPC "https://github.com/netbirdio/wireguard-go/tree/master//ipc"
    click RL "https://github.com/netbirdio/wireguard-go/tree/master//ratelimiter"
    click RP "https://github.com/netbirdio/wireguard-go/tree/master//replay"
    click RWC "https://github.com/netbirdio/wireguard-go/tree/master//rwcancel"
    click TH "https://github.com/netbirdio/wireguard-go/tree/master//tai64n"

    %% Styles
    classDef main fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef interface fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef connection fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef device fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef ipc fill:#D8BFD8,stroke:#333,stroke-width:2px;
    classDef utility fill:#EEE8AA,stroke:#333,stroke-width:2px;
```
