# ivpn/desktop-app architecture

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

- Interactive diagram: https://gitdiagram.com/ivpn/desktop-app
- Repository: https://github.com/ivpn/desktop-app

## Overview

- the **UI** and **CLI** are clients,
- the **daemon** is a privileged back-end service,
- external components (VPN engines, DNS resolver, firewall, etc.) and OS subsystems are orchestrated by the daemon.

##### Main Components (Containers)
- **Electron UI (Client)**
– Renderer process (Vue.js components, views, styles)
– Main process (Electron, IPC layers, “daemon‐client” module)
- **CLI (Client)**
– Go binary with commands & flags
– Communicates with daemon via its internal API layer
- **Daemon (Server/Service)**
– API module (api.go + types) exposing RPC/HTTP over a local socket
– Event Notifier (pushes real-time updates to clients)
– Service Layer (service/*.go orchestrating connect, firewall, DNS, preferences, servers_updater, etc.)
– Protocol Engines (vpn/openvpn, vpn/wireguard, obfsproxy, v2r, kem, ping, splittun)
– OS Helpers (netchange, netinfo, oshelpers platforms, wifiNotifier)
– Launcher & Shell modules (to spawn external binaries/scripts)
- **External Tools & OS Subsystems**
– OpenVPN, WireGuard, DNSCrypt Proxy, Obfsproxy, v2ray executables
– System firewall APIs (Windows WFP, iptables/macOS PF)
– Network stack, routing table

##### Relationships & Data Flows
- UI ⇄ Daemon:
– UI main process calls daemon‐client → daemon API over a local socket
– UI renderer ←→ UI main via Electron IPC
– Real-time events (status updates, connection changes) flow from daemon → UI via event notifier
- CLI ⇄ Daemon:
– CLI issues commands (e.g., `ivpn connect`) → daemon API → daemon service layer → protocol engines → OS
- Daemon → External Tools/OS:
– On “connect,” daemon service spawns OpenVPN or WireGuard subprocess, applies firewall rules via OS Helpers
– Daemon manages DNS via built-in DNS module or spawns DNSCrypt Proxy
– Daemon listens for netchange and wifi events via wifiNotifier and netchange detectors
– Daemon monitors ping and routing via ping module and netinfo

##### Architectural Patterns & Principles
- **Separation of Concerns**: UI/CLI vs. core logic vs. OS orchestration
- **Modular Design**: each service (DNS, firewall, VPN, preferences) in its own package
- **Cross-Platform Abstraction**: oshelpers and platform‐specific files (suffix _darwin, _linux, _windows)
- **Event-Driven Communication**: event_notifier pushing updates, clients subscribe via API
- **External Process Management**: launcher and shell modules spawn/manage external VPN/DNS binaries

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "Electron UI (Client)"
    Renderer["Renderer Process"]:::client
    MainProcess["Main Process"]:::client
    IPC["IPC Layers"]:::client
    DaemonClient["Daemon-Client Module"]:::client
  end

  subgraph "CLI (Client)"
    CLIMain["CLI EntryPoints"]:::client
    CLICommands["Commands & Flags"]:::client
    CLIProtocol["Protocol Client API"]:::client
  end

  subgraph "IVPN Daemon Service"
    API["API Module"]:::daemon
    EventNotifier["Event Notifier"]:::daemon
    ServiceLayer["Service Layer"]:::daemon

    subgraph "Protocol Engines"
      OpenVPN["OpenVPN Engine"]:::daemon
      WireGuard["WireGuard Engine"]:::daemon
      Obfsproxy["Obfsproxy"]:::daemon
      V2ray["v2ray Engine"]:::daemon
      KEM["KEM Helper"]:::daemon
      Ping["Ping Module"]:::daemon
      SplitTun["Split Tunneling"]:::daemon
    end

    subgraph "OS Helpers"
      OSHelpers["OS Abstraction"]:::daemon
      Netchange["Network Change Detection"]:::daemon
      Netinfo["Network Info"]:::daemon
      WifiNotifier["Wi-Fi Notifier"]:::daemon
    end

    subgraph "Launcher & Shell"
      Launcher["Launcher"]:::daemon
      ShellExec["Shell Execution"]:::daemon
    end
  end

  subgraph "External Tools & OS"
    ExtOpenVPN["OpenVPN Binary"]:::external
    ExtWireGuard["WireGuard Tools"]:::external
    DNSCrypt["DNSCrypt Proxy"]:::external
    SystemFW["System Firewall APIs"]:::external
    NetStack["Network Stack"]:::external
  end

  Renderer <--> IPC
  IPC --> MainProcess
  MainProcess -->|"RPC over socket"| API
  EventNotifier -->|"Events"| MainProcess
  CLIMain -->|"Commands"| API
  API --> ServiceLayer
  ServiceLayer --> OpenVPN
  ServiceLayer --> WireGuard
  ServiceLayer --> Obfsproxy
  ServiceLayer --> V2ray
  ServiceLayer --> KEM
  ServiceLayer --> Ping
  ServiceLayer --> SplitTun
  ServiceLayer --> OSHelpers
  OpenVPN --> ExtOpenVPN
  WireGuard --> ExtWireGuard
  ServiceLayer --> DNSCrypt
  OSHelpers --> SystemFW
  OSHelpers --> NetStack
  OSHelpers --> DNSCrypt
  Launcher --> ExtOpenVPN
  Launcher --> ExtWireGuard
  Launcher --> DNSCrypt

  click Renderer "https://github.com/ivpn/desktop-app/tree/master/ui/src/"
  click MainProcess "https://github.com/ivpn/desktop-app/blob/master/ui/src/main.js"
  click IPC "https://github.com/ivpn/desktop-app/tree/master/ui/src/ipc/"
  click DaemonClient "https://github.com/ivpn/desktop-app/tree/master/ui/src/daemon-client/"
  click CLIMain "https://github.com/ivpn/desktop-app/blob/master/cli/main.go"
  click CLICommands "https://github.com/ivpn/desktop-app/tree/master/cli/commands/"
  click CLIProtocol "https://github.com/ivpn/desktop-app/blob/master/cli/protocol/client.go"
  click API "https://github.com/ivpn/desktop-app/blob/master/daemon/api/api.go"
  click EventNotifier "https://github.com/ivpn/desktop-app/blob/master/daemon/events_notifier.go"
  click ServiceLayer "https://github.com/ivpn/desktop-app/blob/master/daemon/service/service.go"
  click OpenVPN "https://github.com/ivpn/desktop-app/tree/master/daemon/vpn/openvpn/"
  click WireGuard "https://github.com/ivpn/desktop-app/tree/master/daemon/vpn/wireguard/"
  click Obfsproxy "https://github.com/ivpn/desktop-app/blob/master/daemon/obfsproxy/obfsproxy.go"
  click V2ray "https://github.com/ivpn/desktop-app/tree/master/daemon/v2r/"
  click KEM "https://github.com/ivpn/desktop-app/tree/master/daemon/kem/"
  click Ping "https://github.com/ivpn/desktop-app/tree/master/daemon/ping/"
  click SplitTun "https://github.com/ivpn/desktop-app/tree/master/daemon/splittun/"
  click OSHelpers "https://github.com/ivpn/desktop-app/tree/master/daemon/oshelpers/"
  click Netchange "https://github.com/ivpn/desktop-app/tree/master/daemon/netchange/"
  click Netinfo "https://github.com/ivpn/desktop-app/tree/master/daemon/netinfo/"
  click WifiNotifier "https://github.com/ivpn/desktop-app/tree/master/daemon/wiFiNotifier/"
  click Launcher "https://github.com/ivpn/desktop-app/blob/master/daemon/launcher.go"
  click ShellExec "https://github.com/ivpn/desktop-app/blob/master/daemon/shell/exec.go"

  classDef client fill:#BBDEFB,stroke:#333,stroke-width:1px
  classDef daemon fill:#C8E6C9,stroke:#333,stroke-width:1px
  classDef external fill:#EEEEEE,stroke:#333,stroke-width:1px
```
