# chrisbrace/ha-vpn-watch architecture

> Architecture diagram of the GitHub repository chrisbrace/ha-vpn-watch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chrisbrace/ha-vpn-watch
- Repository: https://github.com/chrisbrace/ha-vpn-watch

## Overview

#### Purpose and Host Runtime

WireGuard VPN Watch is a Home Assistant custom integration. It polls a Linux WireGuard gateway over SSH, evaluates peer handshake freshness, and exposes per-peer connection entities for automations and dashboards. Home Assistant loads it from `custom_components/wg_vpn_watch/`, with integration metadata in `custom_components/wg_vpn_watch/manifest.json`.

#### Integration Lifecycle and Setup

`custom_components/wg_vpn_watch/__init__.py` owns Home Assistant entry setup/unload and wires configured entries to runtime services. `custom_components/wg_vpn_watch/config_flow.py` implements initial setup and options editing: it collects gateway/SSH/interface settings, discovers current peers, and persists friendly names keyed by WireGuard public key. UI labels and flow text are defined in `custom_components/wg_vpn_watch/strings.json`.

#### Gateway Access Boundary

`custom_components/wg_vpn_watch/ssh.py` is the remote-access boundary. It connects to the configured Linux gateway and executes the configured command template, normally `wg show {interface} dump`; deployments may instead use passwordless `sudo`. SSH host, port, credentials, command, and WireGuard interface are integration configuration rather than entity concerns.

#### WireGuard Data Interpretation

`custom_components/wg_vpn_watch/wireguard.py` converts `wg show ... dump` output into peer records, including public keys and latest handshake timestamps. This isolates WireGuard CLI-format parsing from Home Assistant lifecycle and presentation logic. The primary raw-data flow is: SSH command output → parser → peer handshake data.

#### Polling and Connection State

`custom_components/wg_vpn_watch/coordinator.py` is the central refresh stage. It periodically retrieves and parses gateway state, compares each peer’s latest handshake against the configured timeout, and maintains observed-connected timing. A peer is connected only when its handshake is recent; displayed duration starts when this integration instance first observes connectivity and resets on reload/restart.

#### Entity Projection

`custom_components/wg_vpn_watch/binary_sensor.py` projects coordinator state as a boolean connected/disconnected entity per configured peer, suited to automations. `custom_components/wg_vpn_watch/sensor.py` exposes a status-oriented entity per peer, including connection state and observed duration. Both entity families consume shared coordinator data rather than independently querying the gateway.

#### Configuration and Identity Boundaries

`custom_components/wg_vpn_watch/const.py` centralizes integration identifiers, defaults, and configuration keys used across setup, coordinator, and platforms. Peer identity is the WireGuard public key; friendly names are user-managed labels. Options changes rediscover peers and trigger integration reload/entity recreation, making configuration the boundary between gateway-discovered topology and Home Assistant entity naming.

Main entry points: [`custom_components/wg_vpn_watch/__init__.py`](https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/__init__.py) (Setup and unload), [`custom_components/wg_vpn_watch/coordinator.py`](https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/coordinator.py) (Polling coordinator), [`custom_components/wg_vpn_watch/config_flow.py`](https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/config_flow.py) (Setup and options flow), [`custom_components/wg_vpn_watch/ssh.py`](https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/ssh.py) (SSH command access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ha["Home Assistant"]
  node_manifest["Integration metadata<br/>manifest<br/>[manifest.json]"]
  node_lifecycle["Setup and unload<br/>integration lifecycle<br/>[__init__.py]"]
  node_const["Constants and config keys<br/>shared constants<br/>[const.py]"]
  node_coordinator["Polling coordinator<br/>refresh coordinator<br/>[coordinator.py]"]
end

subgraph group_config["Configuration"]
  node_config_flow["Setup and options flow<br/>config flow<br/>[config_flow.py]"]
  node_strings["Flow UI text<br/>localization<br/>[strings.json]"]
  node_entry_config[("Configured entry<br/>Home Assistant config entry")]
end

subgraph group_gateway["Gateway data"]
  node_gateway{{"Linux WireGuard gateway<br/>remote host"}}
  node_ssh["SSH command access<br/>gateway adapter<br/>[ssh.py]"]
  node_wg_dump["wg show dump output<br/>CLI data"]
  node_parser["WireGuard dump parser<br/>[wireguard.py]"]
end

subgraph group_entities["Entity projection"]
  node_binary_sensor["Connection entities<br/>binary sensor platform<br/>[binary_sensor.py]"]
  node_sensor["Status entities<br/>sensor platform<br/>[sensor.py]"]
end

node_manifest -->|"loads integration"| node_lifecycle
node_const -->|"shared keys"| node_lifecycle
node_const -->|"defaults and keys"| node_config_flow
node_strings -->|"labels flow"| node_config_flow
node_config_flow -->|"creates and updates"| node_entry_config
node_entry_config -->|"sets up entry"| node_lifecycle
node_lifecycle -->|"creates runtime"| node_coordinator
node_lifecycle -->|"forwards platform"| node_binary_sensor
node_lifecycle -->|"forwards platform"| node_sensor
node_entry_config -->|"SSH, command, interface"| node_ssh
node_ssh -->|"connects and executes"| node_gateway
node_gateway -->|"returns"| node_wg_dump
node_wg_dump -->|"parses"| node_parser
node_ssh -->|"retrieves output"| node_coordinator
node_parser -->|"peer handshakes"| node_coordinator
node_entry_config -->|"timeout and peer names"| node_coordinator
node_coordinator -->|"shared peer state"| node_binary_sensor
node_coordinator -->|"shared peer state"| node_sensor
node_config_flow -.->|"options reload"| node_lifecycle

click node_manifest "https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/manifest.json"
click node_lifecycle "https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/__init__.py"
click node_const "https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/const.py"
click node_config_flow "https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/config_flow.py"
click node_strings "https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/strings.json"
click node_ssh "https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/ssh.py"
click node_parser "https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/wireguard.py"
click node_coordinator "https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/coordinator.py"
click node_binary_sensor "https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/binary_sensor.py"
click node_sensor "https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/sensor.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_manifest,node_lifecycle,node_const,node_coordinator toneBlue
class node_config_flow,node_strings,node_entry_config toneAmber
class node_gateway,node_ssh,node_wg_dump,node_parser toneMint
class node_binary_sensor,node_sensor toneRose
```

## Components

### Home Assistant

- [Integration metadata](https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/manifest.json): manifest · `custom_components/wg_vpn_watch/manifest.json`
- [Setup and unload](https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/__init__.py): integration lifecycle · `custom_components/wg_vpn_watch/__init__.py`
- [Constants and config keys](https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/const.py): shared constants · `custom_components/wg_vpn_watch/const.py`
- [Polling coordinator](https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/coordinator.py): refresh coordinator · Evaluates handshake freshness and observed connection duration. · `custom_components/wg_vpn_watch/coordinator.py`

### Configuration

- [Setup and options flow](https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/config_flow.py): config flow · Collects gateway settings and manages peer names. · `custom_components/wg_vpn_watch/config_flow.py`
- [Flow UI text](https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/strings.json): localization · `custom_components/wg_vpn_watch/strings.json`
- **Configured entry**: Home Assistant config entry · Stores SSH, interface, timeout, and public-key-based friendly names.

### Gateway data

- **Linux WireGuard gateway**: remote host
- [SSH command access](https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/ssh.py): gateway adapter · Runs the configured WireGuard command template. · `custom_components/wg_vpn_watch/ssh.py`
- **wg show dump output**: CLI data
- [WireGuard dump parser](https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/wireguard.py): parser · Extracts peer public keys and handshake timestamps. · `custom_components/wg_vpn_watch/wireguard.py`

### Entity projection

- [Connection entities](https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/binary_sensor.py): binary sensor platform · One connected/disconnected entity per configured peer. · `custom_components/wg_vpn_watch/binary_sensor.py`
- [Status entities](https://github.com/chrisbrace/ha-vpn-watch/blob/main/custom_components/wg_vpn_watch/sensor.py): sensor platform · One status and observed-duration entity per configured peer. · `custom_components/wg_vpn_watch/sensor.py`

## Connections

- Integration metadata → Setup and unload: loads integration
- Constants and config keys → Setup and unload: shared keys
- Constants and config keys → Setup and options flow: defaults and keys
- Flow UI text → Setup and options flow: labels flow
- Setup and options flow → Configured entry: creates and updates
- Configured entry → Setup and unload: sets up entry
- Setup and unload → Polling coordinator: creates runtime
- Setup and unload → Connection entities: forwards platform
- Setup and unload → Status entities: forwards platform
- Configured entry → SSH command access: SSH, command, interface
- SSH command access → Linux WireGuard gateway: connects and executes
- Linux WireGuard gateway → wg show dump output: returns
- wg show dump output → WireGuard dump parser: parses
- SSH command access → Polling coordinator: retrieves output
- WireGuard dump parser → Polling coordinator: peer handshakes
- Configured entry → Polling coordinator: timeout and peer names
- Polling coordinator → Connection entities: shared peer state
- Polling coordinator → Status entities: shared peer state
- Setup and options flow → Setup and unload: options reload · Rediscovery changes entity topology and naming.
