# gaboei/watchdogvpn architecture

> Architecture diagram of the GitHub repository gaboei/watchdogvpn, 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/gaboei/watchdogvpn
- Repository: https://github.com/gaboei/watchdogvpn

## Overview

WatchdogVPN is a Linux network-control plane, not just a tunnel launcher. The main workflow is operator command → daemon IPC → runtime action → protocol driver and protected network state, with rotation and watchdog recovery preserving connectivity. Separate policy stages decide routes and DNS behavior; persistent profiles, providers and rules supply configuration. The README also documents diagnostics, backups, metrics and protocol integrations. The sampled sources establish several internals, but many feature links are supported only at the product/module level, so uncertain call relationships are omitted.

Main entry points: [`daemon/runtime_worker.py`](https://github.com/gaboei/watchdogvpn/blob/main/daemon/runtime_worker.py) (Runtime worker), [`cli/main.py`](https://github.com/gaboei/watchdogvpn/blob/main/cli/main.py) (CLI commands), [`daemon/main.py`](https://github.com/gaboei/watchdogvpn/blob/main/daemon/main.py) (Daemon startup), [`daemon/ipc_server.py`](https://github.com/gaboei/watchdogvpn/blob/main/daemon/ipc_server.py) (IPC server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator interface"]
  node_cli["CLI commands<br/>[main.py]"]
  node_tui["Terminal UI"]
  node_ipc_client["IPC client<br/>[client.py]"]
end

subgraph group_runtime["Daemon runtime"]
  node_daemon["Daemon startup<br/>[main.py]"]
  node_ipc_server["IPC server<br/>[ipc_server.py]"]
  node_worker["Runtime worker<br/>[runtime_worker.py]"]
  node_watchdog["Watchdog loop<br/>[watchdog_loop.py]"]
  node_rotation_loop["Rotation loop"]
  node_rotation["Rotation and recovery<br/>[rotation_engine.py]"]
  node_drivers["Protocol drivers"]
end

subgraph group_policy["Traffic policy"]
  node_rules["Rule evaluation<br/>[rule_engine.py]"]
  node_app_policy["App policy"]
  node_node_groups["Node selection"]
  node_route_chains["Route chains<br/>[runtime.py]"]
end

subgraph group_network["Network safety"]
  node_dns["DNS policy"]
  node_dns_state["Resolver state<br/>[state_manager.py]"]
  node_kill_switch["Kill switch<br/>[kill_switch.py]"]
end

subgraph group_state["Configuration and insight"]
  node_profiles["Profiles and providers"]
  node_profile_store[("Profile store<br/>[profile_store.py]")]
  node_provider_store[("Provider store<br/>[provider_store.py]")]
  node_diagnostics["Diagnostics"]
  node_backup["Backup and restore<br/>[backup_manager.py]"]
  node_metrics["Metrics"]
  node_config_state[("Runtime settings<br/>[state_manager.py]")]
end

node_operator(("Operator"))
node_linux_network["Linux networking"]

node_operator -->|"runs commands"| node_cli
node_operator -->|"uses interface"| node_tui
node_cli -->|"sends requests"| node_ipc_client
node_ipc_client -->|"IPC requests"| node_ipc_server
node_daemon -->|"starts"| node_ipc_server
node_daemon -->|"starts"| node_watchdog
node_daemon -->|"starts"| node_rotation_loop
node_ipc_server -->|"dispatches"| node_worker
node_watchdog -->|"checks runtime"| node_worker
node_rotation_loop -->|"schedules"| node_rotation
node_rotation -->|"tries profiles"| node_drivers
node_worker -->|"controls tunnels"| node_drivers
node_drivers -->|"configures tunnel"| node_linux_network
node_profiles -->|"persists profiles"| node_profile_store
node_profiles -->|"persists providers"| node_provider_store
node_worker -->|"evaluates traffic"| node_rules
node_worker -->|"applies policy"| node_app_policy
node_worker -->|"selects nodes"| node_node_groups
node_worker -->|"resolves chains"| node_route_chains
node_worker -->|"applies DNS policy"| node_dns
node_dns -->|"changes resolver state"| node_dns_state
node_dns_state -->|"updates resolvers"| node_linux_network
node_worker -->|"controls protection"| node_kill_switch
node_kill_switch -->|"enforces traffic limits"| node_linux_network
node_worker -->|"reads settings"| node_config_state
node_cli -->|"requests reports"| node_diagnostics
node_cli -->|"exports or restores"| node_backup
node_worker -->|"records runtime"| node_metrics
node_cli -->|"views status"| node_metrics

click node_cli "https://github.com/gaboei/watchdogvpn/blob/main/cli/main.py"
click node_tui "https://github.com/gaboei/watchdogvpn/tree/main/tui/watchdogvpn"
click node_ipc_client "https://github.com/gaboei/watchdogvpn/blob/main/cli/ipc/client.py"
click node_daemon "https://github.com/gaboei/watchdogvpn/blob/main/daemon/main.py"
click node_ipc_server "https://github.com/gaboei/watchdogvpn/blob/main/daemon/ipc_server.py"
click node_worker "https://github.com/gaboei/watchdogvpn/blob/main/daemon/runtime_worker.py"
click node_watchdog "https://github.com/gaboei/watchdogvpn/blob/main/daemon/watchdog_loop.py"
click node_rotation_loop "https://github.com/gaboei/watchdogvpn/blob/main/daemon/scheduled_rotation_loop.py"
click node_rotation "https://github.com/gaboei/watchdogvpn/blob/main/rotation/rotation_engine.py"
click node_drivers "https://github.com/gaboei/watchdogvpn/tree/main/drivers"
click node_profiles "https://github.com/gaboei/watchdogvpn/tree/main/providers"
click node_profile_store "https://github.com/gaboei/watchdogvpn/blob/main/config/profile_store.py"
click node_provider_store "https://github.com/gaboei/watchdogvpn/blob/main/config/provider_store.py"
click node_rules "https://github.com/gaboei/watchdogvpn/blob/main/rules/rule_engine.py"
click node_app_policy "https://github.com/gaboei/watchdogvpn/tree/main/app_policy"
click node_node_groups "https://github.com/gaboei/watchdogvpn/tree/main/node_groups"
click node_route_chains "https://github.com/gaboei/watchdogvpn/blob/main/route_chains/runtime.py"
click node_dns "https://github.com/gaboei/watchdogvpn/tree/main/dns"
click node_dns_state "https://github.com/gaboei/watchdogvpn/blob/main/dns/state_manager.py"
click node_kill_switch "https://github.com/gaboei/watchdogvpn/blob/main/core/kill_switch.py"
click node_diagnostics "https://github.com/gaboei/watchdogvpn/tree/main/diagnostics"
click node_backup "https://github.com/gaboei/watchdogvpn/blob/main/config/backup_manager.py"
click node_metrics "https://github.com/gaboei/watchdogvpn/tree/main/metrics"
click node_config_state "https://github.com/gaboei/watchdogvpn/blob/main/config/state_manager.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_cli,node_tui,node_ipc_client toneBlue
class node_daemon,node_ipc_server,node_worker,node_watchdog,node_rotation_loop,node_rotation,node_drivers toneAmber
class node_rules,node_app_policy,node_node_groups,node_route_chains toneMint
class node_dns,node_dns_state,node_kill_switch toneRose
class node_profiles,node_profile_store,node_provider_store,node_diagnostics,node_backup,node_metrics,node_config_state,node_operator,node_linux_network toneIndigo
```

## Components

### Operator interface

- [CLI commands](https://github.com/gaboei/watchdogvpn/blob/main/cli/main.py): `cli/main.py`
- [Terminal UI](https://github.com/gaboei/watchdogvpn/tree/main/tui/watchdogvpn): `tui/watchdogvpn`
- [IPC client](https://github.com/gaboei/watchdogvpn/blob/main/cli/ipc/client.py): `cli/ipc/client.py`

### Daemon runtime

- [Daemon startup](https://github.com/gaboei/watchdogvpn/blob/main/daemon/main.py): `daemon/main.py`
- [IPC server](https://github.com/gaboei/watchdogvpn/blob/main/daemon/ipc_server.py): `daemon/ipc_server.py`
- [Runtime worker](https://github.com/gaboei/watchdogvpn/blob/main/daemon/runtime_worker.py): `daemon/runtime_worker.py`
- [Watchdog loop](https://github.com/gaboei/watchdogvpn/blob/main/daemon/watchdog_loop.py): `daemon/watchdog_loop.py`
- [Rotation loop](https://github.com/gaboei/watchdogvpn/blob/main/daemon/scheduled_rotation_loop.py): `daemon/scheduled_rotation_loop.py`
- [Rotation and recovery](https://github.com/gaboei/watchdogvpn/blob/main/rotation/rotation_engine.py): `rotation/rotation_engine.py`
- [Protocol drivers](https://github.com/gaboei/watchdogvpn/tree/main/drivers): `drivers`

### Traffic policy

- [Rule evaluation](https://github.com/gaboei/watchdogvpn/blob/main/rules/rule_engine.py): `rules/rule_engine.py`
- [App policy](https://github.com/gaboei/watchdogvpn/tree/main/app_policy): `app_policy`
- [Node selection](https://github.com/gaboei/watchdogvpn/tree/main/node_groups): `node_groups`
- [Route chains](https://github.com/gaboei/watchdogvpn/blob/main/route_chains/runtime.py): `route_chains/runtime.py`

### Network safety

- [DNS policy](https://github.com/gaboei/watchdogvpn/tree/main/dns): `dns`
- [Resolver state](https://github.com/gaboei/watchdogvpn/blob/main/dns/state_manager.py): `dns/state_manager.py`
- [Kill switch](https://github.com/gaboei/watchdogvpn/blob/main/core/kill_switch.py): `core/kill_switch.py`

### Configuration and insight

- [Profiles and providers](https://github.com/gaboei/watchdogvpn/tree/main/providers): `providers`
- [Profile store](https://github.com/gaboei/watchdogvpn/blob/main/config/profile_store.py): `config/profile_store.py`
- [Provider store](https://github.com/gaboei/watchdogvpn/blob/main/config/provider_store.py): `config/provider_store.py`
- [Diagnostics](https://github.com/gaboei/watchdogvpn/tree/main/diagnostics): `diagnostics`
- [Backup and restore](https://github.com/gaboei/watchdogvpn/blob/main/config/backup_manager.py): `config/backup_manager.py`
- [Metrics](https://github.com/gaboei/watchdogvpn/tree/main/metrics): `metrics`
- [Runtime settings](https://github.com/gaboei/watchdogvpn/blob/main/config/state_manager.py): `config/state_manager.py`

### Other components

- **Operator**
- **Linux networking**

## Connections

- Operator → CLI commands: runs commands
- Operator → Terminal UI: uses interface
- CLI commands → IPC client: sends requests
- IPC client → IPC server: IPC requests
- Daemon startup → IPC server: starts
- Daemon startup → Watchdog loop: starts
- Daemon startup → Rotation loop: starts
- IPC server → Runtime worker: dispatches
- Watchdog loop → Runtime worker: checks runtime
- Rotation loop → Rotation and recovery: schedules
- Rotation and recovery → Protocol drivers: tries profiles
- Runtime worker → Protocol drivers: controls tunnels
- Protocol drivers → Linux networking: configures tunnel
- Profiles and providers → Profile store: persists profiles
- Profiles and providers → Provider store: persists providers
- Runtime worker → Rule evaluation: evaluates traffic
- Runtime worker → App policy: applies policy
- Runtime worker → Node selection: selects nodes
- Runtime worker → Route chains: resolves chains
- Runtime worker → DNS policy: applies DNS policy
- DNS policy → Resolver state: changes resolver state
- Resolver state → Linux networking: updates resolvers
- Runtime worker → Kill switch: controls protection
- Kill switch → Linux networking: enforces traffic limits
- Runtime worker → Runtime settings: reads settings
- CLI commands → Diagnostics: requests reports
- CLI commands → Backup and restore: exports or restores
- Runtime worker → Metrics: records runtime
- CLI commands → Metrics: views status