# meteadam/pairvpn-controller architecture

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

- Interactive diagram: https://gitdiagram.com/meteadam/pairvpn-controller
- Repository: https://github.com/meteadam/pairvpn-controller

## Overview

PairVPN Watchdog is a Windows desktop utility that monitors the PairVPN tunnel and quarantines the physical carrier connection when probes fail. The principal flow is adapter discovery, bound tunnel probing, watchdog/alarm handling, then adapter and firewall containment; users can restore connectivity, restart PairVPN, or optionally manage WireSock split tunneling. The main runtime is a monolith, so multiple components share its source path. Edges rely on the README’s architecture and capability descriptions plus the shown calls; unsampled implementation details are not asserted.

Main entry points: [`pairvpn_watchdog.py`](https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py) (Controller UI), [`config.json`](https://github.com/meteadam/pairvpn-controller/blob/main/config.json) (Watchdog Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_gui["Controller UI"]
  node_settings["Watchdog Settings<br/>[config.json]"]
end

subgraph group_monitoring["Tunnel Monitoring"]
  node_discovery["Adapter Discovery"]
  node_probe["Tunnel Probes"]
  node_watchdog["Watchdog State"]
  node_alarm["Alarm Countdown"]
end

subgraph group_protection["Network Protection"]
  node_dns["DNS MTU Optimizer"]
  node_kill["Kill-Switch"]
  node_adapter["Carrier Adapter"]
  node_firewall["Windows Firewall"]
  node_restore["Network Restore"]
  node_restart["PairVPN Restart"]
end

subgraph group_integration["Optional Integrations"]
  node_wiresock["WireSock Manager"]
  node_profile["WireSock Profile"]
end

node_user(("Windows User"))
node_pairvpn["PairVPN Tunnel"]
node_wiresock_service["WireSock Service"]

node_user -->|"uses"| node_gui
node_gui -->|"loads settings"| node_settings
node_gui -->|"starts monitoring"| node_watchdog
node_watchdog -->|"discovers adapters"| node_discovery
node_watchdog -->|"checks tunnel"| node_probe
node_probe -->|"probes through"| node_pairvpn
node_watchdog -->|"starts countdown"| node_alarm
node_watchdog -->|"optimizes when healthy"| node_dns
node_alarm -->|"triggers on expiry"| node_kill
node_kill -->|"disables"| node_adapter
node_kill -->|"blocks outbound"| node_firewall
node_gui -->|"offers recovery"| node_restore
node_restore -->|"re-enables"| node_adapter
node_restore -->|"removes block"| node_firewall
node_gui -->|"offers restart"| node_restart
node_gui -.->|"manages optionally"| node_wiresock
node_wiresock -->|"syncs profile"| node_profile
node_wiresock -->|"controls tunnel"| node_wiresock_service

click node_gui "https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py"
click node_settings "https://github.com/meteadam/pairvpn-controller/blob/main/config.json"
click node_discovery "https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py"
click node_probe "https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py"
click node_watchdog "https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py"
click node_alarm "https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py"
click node_dns "https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py"
click node_kill "https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py"
click node_restore "https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py"
click node_restart "https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py"
click node_wiresock "https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py"

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_gui,node_settings,node_user toneBlue
class node_discovery,node_probe,node_watchdog,node_alarm toneAmber
class node_dns,node_kill,node_adapter,node_firewall,node_restore,node_restart toneMint
class node_wiresock,node_profile toneRose
class node_pairvpn,node_wiresock_service toneIndigo
```

## Components

### User Interface

- [Controller UI](https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py): `pairvpn_watchdog.py`
- [Watchdog Settings](https://github.com/meteadam/pairvpn-controller/blob/main/config.json): `config.json`

### Tunnel Monitoring

- [Adapter Discovery](https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py): `pairvpn_watchdog.py`
- [Tunnel Probes](https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py): `pairvpn_watchdog.py`
- [Watchdog State](https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py): `pairvpn_watchdog.py`
- [Alarm Countdown](https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py): `pairvpn_watchdog.py`

### Network Protection

- [DNS MTU Optimizer](https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py): `pairvpn_watchdog.py`
- [Kill-Switch](https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py): `pairvpn_watchdog.py`
- **Carrier Adapter**
- **Windows Firewall**
- [Network Restore](https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py): `pairvpn_watchdog.py`
- [PairVPN Restart](https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py): `pairvpn_watchdog.py`

### Optional Integrations

- [WireSock Manager](https://github.com/meteadam/pairvpn-controller/blob/main/pairvpn_watchdog.py): `pairvpn_watchdog.py`
- **WireSock Profile**

### Other components

- **Windows User**
- **PairVPN Tunnel**
- **WireSock Service**

## Connections

- Windows User → Controller UI: uses (evidence: `README.md`)
- Controller UI → Watchdog Settings: loads settings (evidence: `pairvpn_watchdog.py`)
- Controller UI → Watchdog State: starts monitoring (evidence: `pairvpn_watchdog.py`)
- Watchdog State → Adapter Discovery: discovers adapters (evidence: `README.md`)
- Watchdog State → Tunnel Probes: checks tunnel (evidence: `README.md`)
- Tunnel Probes → PairVPN Tunnel: probes through (evidence: `README.md`)
- Watchdog State → Alarm Countdown: starts countdown (evidence: `README.md`)
- Watchdog State → DNS MTU Optimizer: optimizes when healthy (evidence: `README.md`)
- Alarm Countdown → Kill-Switch: triggers on expiry (evidence: `README.md`)
- Kill-Switch → Carrier Adapter: disables (evidence: `README.md`)
- Kill-Switch → Windows Firewall: blocks outbound (evidence: `README.md`)
- Controller UI → Network Restore: offers recovery (evidence: `README.md`)
- Network Restore → Carrier Adapter: re-enables (evidence: `README.md`)
- Network Restore → Windows Firewall: removes block (evidence: `README.md`)
- Controller UI → PairVPN Restart: offers restart (evidence: `README.md`)
- Controller UI → WireSock Manager: manages optionally (evidence: `pairvpn_watchdog.py`)
- WireSock Manager → WireSock Profile: syncs profile (evidence: `README.md`)
- WireSock Manager → WireSock Service: controls tunnel (evidence: `README.md`)
