# qvr/unifi-gateway architecture

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

- Interactive diagram: https://gitdiagram.com/qvr/unifi-gateway
- Repository: https://github.com/qvr/unifi-gateway

## Overview

This daemon impersonates a UniFi gateway so a router can be adopted by, and report status to, a UniFi controller. An operator configures the gateway and initiates adoption; the daemon broadcasts discovery messages until adopted, then repeatedly collects router data, builds and encodes informs, sends them to the controller, and handles controller responses. The collector covers interface and host data, DHCP leases, latency, and speed-test results. The README documents these product stages; unsampled implementation details are represented only where the tree or excerpts support them.

Main entry points: [`unifi_gateway.py`](https://github.com/qvr/unifi-gateway/blob/master/unifi_gateway.py) (Gateway daemon), [`datacollector.py`](https://github.com/qvr/unifi-gateway/blob/master/datacollector.py) (Data collector), [`unifi_protocol.py`](https://github.com/qvr/unifi-gateway/blob/master/unifi_protocol.py) (Inform protocol), [`conf/unifi-gateway.conf`](https://github.com/qvr/unifi-gateway/blob/master/conf/unifi-gateway.conf) (Gateway settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_daemon["Daemon lifecycle"]
  node_gateway["Gateway daemon<br/>[unifi_gateway.py]"]
end

subgraph group_telemetry["Router telemetry"]
  node_collector["Data collector<br/>[datacollector.py]"]
  node_helpers["Telemetry formatting<br/>[tools.py]"]
end

subgraph group_protocol["UniFi protocol"]
  node_protocolmod["Inform protocol<br/>[unifi_protocol.py]"]
end

subgraph group_settings["Configuration"]
  node_settingsfile["Gateway settings<br/>[unifi-gateway.conf]"]
end

node_operator(("Operator"))
node_controller(("UniFi controller"))
node_router["Router host"]

node_operator -->|"runs commands"| node_gateway
node_gateway -->|"reads and writes"| node_settingsfile
node_gateway -->|"creates and updates"| node_collector
node_collector -->|"reads system telemetry"| node_router
node_gateway -->|"builds broadcast and inform"| node_protocolmod
node_protocolmod -->|"formats telemetry"| node_helpers
node_gateway -->|"sends discovery broadcast"| node_controller
node_gateway -->|"posts encoded informs"| node_controller
node_controller -->|"returns response"| node_gateway
node_gateway -->|"persists adoption state"| node_settingsfile

click node_gateway "https://github.com/qvr/unifi-gateway/blob/master/unifi_gateway.py"
click node_collector "https://github.com/qvr/unifi-gateway/blob/master/datacollector.py"
click node_helpers "https://github.com/qvr/unifi-gateway/blob/master/tools.py"
click node_protocolmod "https://github.com/qvr/unifi-gateway/blob/master/unifi_protocol.py"
click node_settingsfile "https://github.com/qvr/unifi-gateway/blob/master/conf/unifi-gateway.conf"

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_gateway toneBlue
class node_collector,node_helpers toneAmber
class node_protocolmod,node_router toneMint
class node_settingsfile toneRose
class node_operator,node_controller toneIndigo
```

## Components

### Daemon lifecycle

- [Gateway daemon](https://github.com/qvr/unifi-gateway/blob/master/unifi_gateway.py): `unifi_gateway.py`

### Router telemetry

- [Data collector](https://github.com/qvr/unifi-gateway/blob/master/datacollector.py): `datacollector.py`
- [Telemetry formatting](https://github.com/qvr/unifi-gateway/blob/master/tools.py): `tools.py`

### UniFi protocol

- [Inform protocol](https://github.com/qvr/unifi-gateway/blob/master/unifi_protocol.py): `unifi_protocol.py`

### Configuration

- [Gateway settings](https://github.com/qvr/unifi-gateway/blob/master/conf/unifi-gateway.conf): `conf/unifi-gateway.conf`

### Other components

- **Operator**
- **UniFi controller**
- **Router host**

## Connections

- Operator → Gateway daemon: runs commands
- Gateway daemon → Gateway settings: reads and writes
- Gateway daemon → Data collector: creates and updates
- Data collector → Router host: reads system telemetry
- Gateway daemon → Inform protocol: builds broadcast and inform
- Inform protocol → Telemetry formatting: formats telemetry
- Gateway daemon → UniFi controller: sends discovery broadcast
- Gateway daemon → UniFi controller: posts encoded informs
- UniFi controller → Gateway daemon: returns response
- Gateway daemon → Gateway settings: persists adoption state