# jezza34000/homeassistant_petkit architecture

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

- Interactive diagram: https://gitdiagram.com/jezza34000/homeassistant_petkit
- Repository: https://github.com/jezza34000/homeassistant_petkit

## Overview

This is a Home Assistant custom integration for Petkit devices. Users configure the integration, which obtains device data and exposes device-specific controls and monitoring as Home Assistant entities. MQTT events trigger faster refreshes; separate branches provide notifications, media access, Bluetooth-relay support, and camera streaming. The README documents these capabilities, while sampled source confirms representative command, MQTT, entity, and streaming behavior; some subsystem connections are therefore intentionally left unspecified.

Main entry points: [`custom_components/petkit/coordinator.py`](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/coordinator.py) (Device coordinator), [`custom_components/petkit/__init__.py`](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/__init__.py) (Integration lifecycle), [`custom_components/petkit/agora_api.py`](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/agora_api.py) (Petkit API client), [`custom_components/petkit/camera.py`](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/camera.py) (Camera entity)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and data"]
  node_config["Configuration flow<br/>[config_flow.py]"]
  node_integration["Integration lifecycle<br/>[__init__.py]"]
  node_coordinator["Device coordinator<br/>[coordinator.py]"]
  node_data["Device data<br/>[data.py]"]
  node_api["Petkit API client<br/>[agora_api.py]"]
end

subgraph group_entities["Device entities"]
  node_base_entity["Entity base<br/>[entity.py]"]
  node_controls["Device controls<br/>[button.py]"]
  node_switches["Device settings<br/>[switch.py]"]
  node_sensors["Sensors<br/>[sensor.py]"]
  node_binary_sensors["Binary sensors<br/>[binary_sensor.py]"]
  node_other_entities["Other entity platforms"]
end

subgraph group_media["Media and streaming"]
  node_media["Media access<br/>[media_source.py]"]
  node_images["Device images<br/>[image.py]"]
  node_camera["Camera entity<br/>[camera.py]"]
  node_stream_manager["go2rtc stream manager<br/>[go2rtc_stream.py]"]
  node_whep["WHEP proxy<br/>[whep_proxy.py]"]
  node_signaling["Agora signaling<br/>[agora_websocket.py]"]
  node_agora_rtm["Agora RTM<br/>[agora_rtm.py]"]
  node_sdp["SDP handling<br/>[agora_sdp.py]"]
  node_media_coordinator["Media coordinator<br/>[coordinator.py]"]
end

subgraph group_events["Events and alerts"]
  node_mqtt_listener["MQTT listener<br/>[iot_mqtt.py]"]
  node_notifications["Persistent notifications<br/>[notifications.py]"]
end

node_user(("Home Assistant user"))
node_ha(("Home Assistant"))
node_petkit(("Petkit services/devices"))
node_mqtt(("Petkit MQTT broker"))
node_go2rtc(("go2rtc"))
node_browser(("Browser viewer"))

node_user -->|"configures"| node_config
node_config -->|"sets up"| node_integration
node_integration -->|"initializes"| node_api
node_integration -->|"starts"| node_coordinator
node_coordinator -->|"fetches data"| node_api
node_api -->|"API requests"| node_petkit
node_coordinator -->|"updates"| node_data
node_integration -->|"starts"| node_mqtt_listener
node_mqtt_listener -->|"gets MQTT config"| node_api
node_mqtt_listener -->|"connects"| node_mqtt
node_mqtt_listener -->|"triggers refresh"| node_coordinator
node_integration -->|"sets up"| node_notifications
node_coordinator -->|"provides device updates"| node_notifications
node_integration -->|"provides shared entity"| node_base_entity
node_base_entity -->|"reads device state"| node_coordinator
node_controls -->|"sends commands"| node_api
node_switches -->|"updates settings"| node_api
node_controls -->|"exposes actions"| node_ha
node_switches -->|"exposes settings"| node_ha
node_sensors -->|"reads state"| node_coordinator
node_binary_sensors -->|"reads state"| node_coordinator
node_sensors -->|"exposes measurements"| node_ha
node_binary_sensors -->|"exposes statuses"| node_ha
node_other_entities -->|"exposes entities"| node_ha
node_integration -->|"sets up media"| node_media_coordinator
node_media -->|"reads media"| node_media_coordinator
node_media -->|"provides media"| node_ha
node_images -->|"exposes images"| node_ha
node_camera -->|"reads event images"| node_media_coordinator
node_camera -->|"manages streams"| node_stream_manager
node_stream_manager -.->|"configures streams"| node_go2rtc
node_camera -->|"creates stream sessions"| node_whep
node_whep -->|"forwards signaling"| node_signaling
node_signaling -->|"uses RTM"| node_agora_rtm
node_signaling -->|"handles SDP"| node_sdp
node_whep -.->|"proxies WHEP"| node_go2rtc
node_browser -->|"requests live video"| node_camera
node_camera -->|"returns stream"| node_browser
node_notifications -->|"creates alerts"| node_ha

click node_config "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/config_flow.py"
click node_integration "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/__init__.py"
click node_coordinator "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/coordinator.py"
click node_data "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/data.py"
click node_api "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/agora_api.py"
click node_mqtt_listener "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/iot_mqtt.py"
click node_notifications "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/notifications.py"
click node_base_entity "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/entity.py"
click node_controls "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/button.py"
click node_switches "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/switch.py"
click node_sensors "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/sensor.py"
click node_binary_sensors "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/binary_sensor.py"
click node_other_entities "https://github.com/jezza34000/homeassistant_petkit/tree/main/custom_components/petkit"
click node_media "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/media_source.py"
click node_images "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/image.py"
click node_camera "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/camera.py"
click node_stream_manager "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/go2rtc_stream.py"
click node_whep "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/whep_proxy.py"
click node_signaling "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/agora_websocket.py"
click node_agora_rtm "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/agora_rtm.py"
click node_sdp "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/agora_sdp.py"
click node_media_coordinator "https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/coordinator.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_config,node_integration,node_coordinator,node_data,node_api,node_user,node_browser toneBlue
class node_base_entity,node_controls,node_switches,node_sensors,node_binary_sensors,node_other_entities toneAmber
class node_media,node_images,node_camera,node_stream_manager,node_whep,node_signaling,node_agora_rtm,node_sdp,node_media_coordinator toneMint
class node_mqtt_listener,node_notifications toneRose
class node_ha,node_petkit,node_mqtt,node_go2rtc toneIndigo
```

## Components

### Setup and data

- [Configuration flow](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/config_flow.py): `custom_components/petkit/config_flow.py`
- [Integration lifecycle](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/__init__.py): `custom_components/petkit/__init__.py`
- [Device coordinator](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/coordinator.py): `custom_components/petkit/coordinator.py`
- [Device data](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/data.py): `custom_components/petkit/data.py`
- [Petkit API client](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/agora_api.py): `custom_components/petkit/agora_api.py`

### Device entities

- [Entity base](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/entity.py): `custom_components/petkit/entity.py`
- [Device controls](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/button.py): `custom_components/petkit/button.py`
- [Device settings](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/switch.py): `custom_components/petkit/switch.py`
- [Sensors](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/sensor.py): `custom_components/petkit/sensor.py`
- [Binary sensors](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/binary_sensor.py): `custom_components/petkit/binary_sensor.py`
- [Other entity platforms](https://github.com/jezza34000/homeassistant_petkit/tree/main/custom_components/petkit): `custom_components/petkit`

### Media and streaming

- [Media access](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/media_source.py): `custom_components/petkit/media_source.py`
- [Device images](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/image.py): `custom_components/petkit/image.py`
- [Camera entity](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/camera.py): `custom_components/petkit/camera.py`
- [go2rtc stream manager](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/go2rtc_stream.py): `custom_components/petkit/go2rtc_stream.py`
- [WHEP proxy](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/whep_proxy.py): `custom_components/petkit/whep_proxy.py`
- [Agora signaling](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/agora_websocket.py): `custom_components/petkit/agora_websocket.py`
- [Agora RTM](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/agora_rtm.py): `custom_components/petkit/agora_rtm.py`
- [SDP handling](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/agora_sdp.py): `custom_components/petkit/agora_sdp.py`
- [Media coordinator](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/coordinator.py): `custom_components/petkit/coordinator.py`

### Events and alerts

- [MQTT listener](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/iot_mqtt.py): `custom_components/petkit/iot_mqtt.py`
- [Persistent notifications](https://github.com/jezza34000/homeassistant_petkit/blob/main/custom_components/petkit/notifications.py): `custom_components/petkit/notifications.py`

### Other components

- **Home Assistant user**
- **Home Assistant**
- **Petkit services/devices**
- **Petkit MQTT broker**
- **go2rtc**
- **Browser viewer**

## Connections

- Home Assistant user → Configuration flow: configures
- Configuration flow → Integration lifecycle: sets up
- Integration lifecycle → Petkit API client: initializes
- Integration lifecycle → Device coordinator: starts
- Device coordinator → Petkit API client: fetches data
- Petkit API client → Petkit services/devices: API requests
- Device coordinator → Device data: updates
- Integration lifecycle → MQTT listener: starts
- MQTT listener → Petkit API client: gets MQTT config
- MQTT listener → Petkit MQTT broker: connects
- MQTT listener → Device coordinator: triggers refresh
- Integration lifecycle → Persistent notifications: sets up
- Device coordinator → Persistent notifications: provides device updates
- Integration lifecycle → Entity base: provides shared entity
- Entity base → Device coordinator: reads device state
- Device controls → Petkit API client: sends commands
- Device settings → Petkit API client: updates settings
- Device controls → Home Assistant: exposes actions
- Device settings → Home Assistant: exposes settings
- Sensors → Device coordinator: reads state
- Binary sensors → Device coordinator: reads state
- Sensors → Home Assistant: exposes measurements
- Binary sensors → Home Assistant: exposes statuses
- Other entity platforms → Home Assistant: exposes entities
- Integration lifecycle → Media coordinator: sets up media
- Media access → Media coordinator: reads media
- Media access → Home Assistant: provides media
- Device images → Home Assistant: exposes images
- Camera entity → Media coordinator: reads event images
- Camera entity → go2rtc stream manager: manages streams
- go2rtc stream manager → go2rtc: configures streams
- Camera entity → WHEP proxy: creates stream sessions
- WHEP proxy → Agora signaling: forwards signaling
- Agora signaling → Agora RTM: uses RTM
- Agora signaling → SDP handling: handles SDP
- WHEP proxy → go2rtc: proxies WHEP
- Browser viewer → Camera entity: requests live video
- Camera entity → Browser viewer: returns stream
- Persistent notifications → Home Assistant: creates alerts