# wireguard/wireguard-apple architecture

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

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

## Overview

WireGuard for iOS and macOS manages WireGuard tunnel configurations and VPN operation. Users import or scan a configuration, review or edit it, save it as a managed tunnel, then activate it and inspect status or runtime details. The manager coordinates tunnel lifecycle with the system Network Extension; WireGuardKit configures the packet tunnel and the Go-backed engine. The tree documents ZIP import/export, on-demand rules, and logs as additional capabilities. Sampled excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`Sources/WireGuardApp/Tunnel/TunnelsManager.swift`](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/Tunnel/TunnelsManager.swift) (Tunnel manager), [`Sources/WireGuardApp/UI/iOS/ViewController/TunnelsListTableViewController.swift`](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/iOS/ViewController/TunnelsListTableViewController.swift) (iOS screens), [`Sources/WireGuardApp/UI/macOS/ViewController/TunnelsListTableViewController.swift`](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/macOS/ViewController/TunnelsListTableViewController.swift) (macOS screens), [`Sources/WireGuardApp/UI/macOS/ViewController/TunnelEditViewController.swift`](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/macOS/ViewController/TunnelEditViewController.swift) (macOS editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Client applications"]
  node_ios["iOS screens"]
  node_mac["macOS screens"]
  node_iosedit["iOS editor"]
  node_macedit["macOS editor"]
  node_iosdetail["iOS details"]
  node_macdetail["macOS details"]
  node_logview["Log viewer"]
end

subgraph group_management["Tunnel management"]
  node_importer["Tunnel importer"]
  node_zipin["ZIP import<br/>[ZipImporter.swift]"]
  node_zipout["ZIP export<br/>[ZipExporter.swift]"]
  node_viewmodel["Tunnel model"]
  node_manager["Tunnel manager"]
  node_ondemand["On-demand rules"]
end

subgraph group_engine["VPN engine"]
  node_config["Tunnel configuration"]
  node_adapter["WireGuard adapter"]
  node_settings["Packet settings"]
  node_provider["Packet tunnel provider"]
  node_go["WireGuard Go<br/>[api-apple.go]"]
  node_keycrypto["Key crypto<br/>[key.c]"]
end

subgraph group_shared["Shared services"]
  node_keychain[("Keychain<br/>[Keychain.swift]")]
  node_logs[("Tunnel logs<br/>[Logger.swift]")]
  node_sharedfiles[("App group files")]
end

node_user(("User"))
node_systemvpn["Network Extension"]

node_user -->|"uses"| node_ios
node_user -->|"uses"| node_mac
node_ios -->|"imports configs"| node_importer
node_ios -->|"selects archive"| node_zipin
node_ios -->|"edits tunnel"| node_iosedit
node_mac -->|"edits tunnel"| node_macedit
node_iosedit -->|"updates fields"| node_viewmodel
node_macedit -->|"parses config"| node_config
node_iosedit -->|"saves tunnel"| node_manager
node_macedit -->|"saves tunnel"| node_manager
node_importer -->|"adds tunnel"| node_manager
node_zipin -->|"provides configs"| node_importer
node_ios -->|"activates tunnel"| node_manager
node_mac -->|"manages tunnels"| node_manager
node_iosdetail -->|"controls tunnel"| node_manager
node_macdetail -->|"controls tunnel"| node_manager
node_iosdetail -->|"edits rules"| node_ondemand
node_macedit -->|"sets rules"| node_ondemand
node_manager -->|"starts provider"| node_systemvpn
node_systemvpn -->|"invokes"| node_provider
node_provider -->|"configures engine"| node_adapter
node_adapter -->|"generates settings"| node_settings
node_adapter -->|"controls tunnel"| node_go
node_adapter -->|"derives keys"| node_keycrypto
node_provider -->|"sets packet routes"| node_systemvpn
node_manager -.->|"stores credentials"| node_keychain
node_provider -->|"records events"| node_logs
node_logview -->|"reads logs"| node_logs
node_logs -->|"persists log file"| node_sharedfiles
node_mac -->|"exports configs"| node_zipout

click node_ios "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/iOS/ViewController/TunnelsListTableViewController.swift"
click node_mac "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/macOS/ViewController/TunnelsListTableViewController.swift"
click node_iosedit "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/iOS/ViewController/TunnelEditTableViewController.swift"
click node_macedit "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/macOS/ViewController/TunnelEditViewController.swift"
click node_iosdetail "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/iOS/ViewController/TunnelDetailTableViewController.swift"
click node_macdetail "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/macOS/ViewController/TunnelDetailTableViewController.swift"
click node_importer "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/TunnelImporter.swift"
click node_zipin "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/ZipArchive/ZipImporter.swift"
click node_zipout "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/ZipArchive/ZipExporter.swift"
click node_viewmodel "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/TunnelViewModel.swift"
click node_manager "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/Tunnel/TunnelsManager.swift"
click node_ondemand "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/ActivateOnDemandViewModel.swift"
click node_config "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardKit/TunnelConfiguration.swift"
click node_adapter "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardKit/WireGuardAdapter.swift"
click node_settings "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardKit/PacketTunnelSettingsGenerator.swift"
click node_provider "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardNetworkExtension/PacketTunnelProvider.swift"
click node_go "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardKitGo/api-apple.go"
click node_keycrypto "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardKitC/key.c"
click node_keychain "https://github.com/wireguard/wireguard-apple/blob/master/Sources/Shared/Keychain.swift"
click node_logs "https://github.com/wireguard/wireguard-apple/blob/master/Sources/Shared/Logging/Logger.swift"
click node_logview "https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/LogViewHelper.swift"
click node_sharedfiles "https://github.com/wireguard/wireguard-apple/blob/master/Sources/Shared/FileManager%2BExtension.swift"

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_ios,node_mac,node_iosedit,node_macedit,node_iosdetail,node_macdetail,node_logview,node_user toneBlue
class node_importer,node_zipin,node_zipout,node_viewmodel,node_manager,node_ondemand toneAmber
class node_config,node_adapter,node_settings,node_provider,node_go,node_keycrypto toneMint
class node_keychain,node_logs,node_sharedfiles toneRose
class node_systemvpn toneIndigo
```

## Components

### Client applications

- [iOS screens](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/iOS/ViewController/TunnelsListTableViewController.swift): `Sources/WireGuardApp/UI/iOS/ViewController/TunnelsListTableViewController.swift`
- [macOS screens](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/macOS/ViewController/TunnelsListTableViewController.swift): `Sources/WireGuardApp/UI/macOS/ViewController/TunnelsListTableViewController.swift`
- [iOS editor](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/iOS/ViewController/TunnelEditTableViewController.swift): `Sources/WireGuardApp/UI/iOS/ViewController/TunnelEditTableViewController.swift`
- [macOS editor](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/macOS/ViewController/TunnelEditViewController.swift): `Sources/WireGuardApp/UI/macOS/ViewController/TunnelEditViewController.swift`
- [iOS details](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/iOS/ViewController/TunnelDetailTableViewController.swift): `Sources/WireGuardApp/UI/iOS/ViewController/TunnelDetailTableViewController.swift`
- [macOS details](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/macOS/ViewController/TunnelDetailTableViewController.swift): `Sources/WireGuardApp/UI/macOS/ViewController/TunnelDetailTableViewController.swift`
- [Log viewer](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/LogViewHelper.swift): `Sources/WireGuardApp/UI/LogViewHelper.swift`

### Tunnel management

- [Tunnel importer](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/TunnelImporter.swift): `Sources/WireGuardApp/UI/TunnelImporter.swift`
- [ZIP import](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/ZipArchive/ZipImporter.swift): `Sources/WireGuardApp/ZipArchive/ZipImporter.swift`
- [ZIP export](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/ZipArchive/ZipExporter.swift): `Sources/WireGuardApp/ZipArchive/ZipExporter.swift`
- [Tunnel model](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/TunnelViewModel.swift): `Sources/WireGuardApp/UI/TunnelViewModel.swift`
- [Tunnel manager](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/Tunnel/TunnelsManager.swift): `Sources/WireGuardApp/Tunnel/TunnelsManager.swift`
- [On-demand rules](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardApp/UI/ActivateOnDemandViewModel.swift): `Sources/WireGuardApp/UI/ActivateOnDemandViewModel.swift`

### VPN engine

- [Tunnel configuration](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardKit/TunnelConfiguration.swift): `Sources/WireGuardKit/TunnelConfiguration.swift`
- [WireGuard adapter](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardKit/WireGuardAdapter.swift): `Sources/WireGuardKit/WireGuardAdapter.swift`
- [Packet settings](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardKit/PacketTunnelSettingsGenerator.swift): `Sources/WireGuardKit/PacketTunnelSettingsGenerator.swift`
- [Packet tunnel provider](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardNetworkExtension/PacketTunnelProvider.swift): `Sources/WireGuardNetworkExtension/PacketTunnelProvider.swift`
- [WireGuard Go](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardKitGo/api-apple.go): `Sources/WireGuardKitGo/api-apple.go`
- [Key crypto](https://github.com/wireguard/wireguard-apple/blob/master/Sources/WireGuardKitC/key.c): `Sources/WireGuardKitC/key.c`

### Shared services

- [Keychain](https://github.com/wireguard/wireguard-apple/blob/master/Sources/Shared/Keychain.swift): `Sources/Shared/Keychain.swift`
- [Tunnel logs](https://github.com/wireguard/wireguard-apple/blob/master/Sources/Shared/Logging/Logger.swift): `Sources/Shared/Logging/Logger.swift`
- [App group files](https://github.com/wireguard/wireguard-apple/blob/master/Sources/Shared/FileManager%2BExtension.swift): `Sources/Shared/FileManager+Extension.swift`

### Other components

- **User**
- **Network Extension**

## Connections

- User → iOS screens: uses
- User → macOS screens: uses
- iOS screens → Tunnel importer: imports configs
- iOS screens → ZIP import: selects archive
- iOS screens → iOS editor: edits tunnel
- macOS screens → macOS editor: edits tunnel
- iOS editor → Tunnel model: updates fields
- macOS editor → Tunnel configuration: parses config
- iOS editor → Tunnel manager: saves tunnel
- macOS editor → Tunnel manager: saves tunnel
- Tunnel importer → Tunnel manager: adds tunnel
- ZIP import → Tunnel importer: provides configs
- iOS screens → Tunnel manager: activates tunnel
- macOS screens → Tunnel manager: manages tunnels
- iOS details → Tunnel manager: controls tunnel
- macOS details → Tunnel manager: controls tunnel
- iOS details → On-demand rules: edits rules
- macOS editor → On-demand rules: sets rules
- Tunnel manager → Network Extension: starts provider
- Network Extension → Packet tunnel provider: invokes
- Packet tunnel provider → WireGuard adapter: configures engine
- WireGuard adapter → Packet settings: generates settings
- WireGuard adapter → WireGuard Go: controls tunnel
- WireGuard adapter → Key crypto: derives keys
- Packet tunnel provider → Network Extension: sets packet routes
- Tunnel manager → Keychain: stores credentials
- Packet tunnel provider → Tunnel logs: records events
- Log viewer → Tunnel logs: reads logs
- Tunnel logs → App group files: persists log file
- macOS screens → ZIP export: exports configs