# zalviandyr/homebridge-tuya architecture

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

- Interactive diagram: https://gitdiagram.com/zalviandyr/homebridge-tuya
- Repository: https://github.com/zalviandyr/homebridge-tuya

## Overview

Homebridge Tuya is a plugin that exposes Tuya Cloud devices as HomeKit accessories. The principal flow is platform configuration and authentication, device discovery through either Custom assets or Smart Home homes, then accessory creation and state/command translation. The README also documents broad device-category support, Tap-to-Run scenes, device overrides, infrared control, and camera streaming. Several relationships are grounded in excerpts or SOURCE INDEX references; unsampled feature wiring is shown only where the README documents it.

Main entry points: [`src/device/TuyaDeviceManager.ts`](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/device/TuyaDeviceManager.ts) (Device operations), [`src/platform.ts`](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/platform.ts) (Platform lifecycle), [`src/accessory/BaseAccessory.ts`](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/accessory/BaseAccessory.ts) (Accessory state and commands), [`src/core/TuyaOpenAPI.ts`](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/core/TuyaOpenAPI.ts) (Tuya HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Homebridge Platform"]
  node_platform_plugin["Platform lifecycle<br/>[platform.ts]"]
  node_config["Config and overrides<br/>[config.ts]"]
  node_factory["Accessory factory"]
end

subgraph group_discovery["Tuya Discovery"]
  node_home_manager["Smart Home discovery"]
  node_custom_manager["Custom asset discovery"]
  node_device_manager["Device operations"]
  node_device_model["Device and DP model<br/>[TuyaDevice.ts]"]
end

subgraph group_accessories["HomeKit Accessories"]
  node_base_accessory["Accessory state and commands<br/>[BaseAccessory.ts]"]
  node_device_categories["Device category handlers"]
  node_characteristics["HomeKit characteristic mapping"]
  node_scenes["Tap-to-Run scenes<br/>[SceneAccessory.ts]"]
  node_camera["Camera accessory<br/>[CameraAccessory.ts]"]
end

subgraph group_cloud["Cloud Connectivity"]
  node_cloud_api["Tuya HTTP API<br/>[TuyaOpenAPI.ts]"]
  node_cloud_mq["Tuya event MQTT<br/>[TuyaOpenMQ.ts]"]
  node_logger["Logging<br/>[Logger.ts]"]
end

subgraph group_media["Media and IR"]
  node_stream_delegate["Camera streaming"]
  node_recording["Recording delegate"]
  node_ffmpeg["FFmpeg process"]
  node_ir_accessories["Infrared accessories"]
  node_ir_tools["Infrared utilities<br/>[InfraredTool.ts]"]
end

node_user(("Homebridge user"))
node_tuya_cloud(("Tuya Cloud"))
node_homekit(("HomeKit"))

node_user -->|"configures"| node_platform_plugin
node_platform_plugin -->|"validates"| node_config
node_platform_plugin -->|"creates"| node_cloud_api
node_platform_plugin -->|"selects Custom"| node_custom_manager
node_platform_plugin -->|"selects Smart Home"| node_home_manager
node_platform_plugin -->|"creates handlers"| node_factory
node_home_manager -->|"extends"| node_device_manager
node_custom_manager -->|"extends"| node_device_manager
node_custom_manager -->|"queries assets"| node_cloud_api
node_device_manager -->|"requests device data"| node_cloud_api
node_device_manager -->|"uses events"| node_cloud_mq
node_device_manager -->|"builds devices"| node_device_model
node_cloud_api -->|"sends HTTP"| node_tuya_cloud
node_cloud_mq -->|"connects MQTT"| node_tuya_cloud
node_factory -->|"creates handlers"| node_base_accessory
node_factory -->|"dispatches categories"| node_device_categories
node_base_accessory -->|"sends commands"| node_device_manager
node_device_categories -.->|"specializes"| node_base_accessory
node_device_categories -->|"configures"| node_characteristics
node_base_accessory -.->|"updates state"| node_homekit
node_homekit -.->|"sets characteristics"| node_base_accessory
node_platform_plugin -.->|"supports scenes"| node_scenes
node_camera -->|"creates stream delegate"| node_stream_delegate
node_stream_delegate -->|"uses"| node_recording
node_stream_delegate -->|"starts process"| node_ffmpeg
node_stream_delegate -.->|"requests video stream"| node_tuya_cloud
node_ir_accessories -.->|"sends IR commands"| node_device_manager
node_ir_tools -.->|"supports control"| node_ir_accessories
node_cloud_api -->|"logs"| node_logger
node_device_manager -->|"logs"| node_logger

click node_platform_plugin "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/platform.ts"
click node_config "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/config.ts"
click node_factory "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/accessory/AccessoryFactory.ts"
click node_home_manager "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/device/TuyaHomeDeviceManager.ts"
click node_custom_manager "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/device/TuyaCustomDeviceManager.ts"
click node_device_manager "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/device/TuyaDeviceManager.ts"
click node_device_model "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/device/TuyaDevice.ts"
click node_cloud_api "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/core/TuyaOpenAPI.ts"
click node_cloud_mq "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/core/TuyaOpenMQ.ts"
click node_base_accessory "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/accessory/BaseAccessory.ts"
click node_device_categories "https://github.com/zalviandyr/homebridge-tuya/tree/latest/src/accessory"
click node_characteristics "https://github.com/zalviandyr/homebridge-tuya/tree/latest/src/accessory/characteristic"
click node_scenes "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/accessory/SceneAccessory.ts"
click node_camera "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/accessory/CameraAccessory.ts"
click node_stream_delegate "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/util/TuyaStreamDelegate.ts"
click node_recording "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/util/TuyaRecordingDelegate.ts"
click node_ffmpeg "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/util/FfmpegStreamingProcess.ts"
click node_ir_accessories "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/accessory/IRControlHubAccessory.ts"
click node_ir_tools "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/util/InfraredTool.ts"
click node_logger "https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/util/Logger.ts"

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_platform_plugin,node_config,node_factory,node_user toneBlue
class node_home_manager,node_custom_manager,node_device_manager,node_device_model toneAmber
class node_base_accessory,node_device_categories,node_characteristics,node_scenes,node_camera toneMint
class node_cloud_api,node_cloud_mq,node_logger toneRose
class node_stream_delegate,node_recording,node_ffmpeg,node_ir_accessories,node_ir_tools,node_tuya_cloud,node_homekit toneIndigo
```

## Components

### Homebridge Platform

- [Platform lifecycle](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/platform.ts): `src/platform.ts`
- [Config and overrides](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/config.ts): `src/config.ts`
- [Accessory factory](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/accessory/AccessoryFactory.ts): `src/accessory/AccessoryFactory.ts`

### Tuya Discovery

- [Smart Home discovery](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/device/TuyaHomeDeviceManager.ts): `src/device/TuyaHomeDeviceManager.ts`
- [Custom asset discovery](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/device/TuyaCustomDeviceManager.ts): `src/device/TuyaCustomDeviceManager.ts`
- [Device operations](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/device/TuyaDeviceManager.ts): `src/device/TuyaDeviceManager.ts`
- [Device and DP model](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/device/TuyaDevice.ts): `src/device/TuyaDevice.ts`

### HomeKit Accessories

- [Accessory state and commands](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/accessory/BaseAccessory.ts): `src/accessory/BaseAccessory.ts`
- [Device category handlers](https://github.com/zalviandyr/homebridge-tuya/tree/latest/src/accessory): `src/accessory`
- [HomeKit characteristic mapping](https://github.com/zalviandyr/homebridge-tuya/tree/latest/src/accessory/characteristic): `src/accessory/characteristic`
- [Tap-to-Run scenes](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/accessory/SceneAccessory.ts): `src/accessory/SceneAccessory.ts`
- [Camera accessory](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/accessory/CameraAccessory.ts): `src/accessory/CameraAccessory.ts`

### Cloud Connectivity

- [Tuya HTTP API](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/core/TuyaOpenAPI.ts): `src/core/TuyaOpenAPI.ts`
- [Tuya event MQTT](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/core/TuyaOpenMQ.ts): `src/core/TuyaOpenMQ.ts`
- [Logging](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/util/Logger.ts): `src/util/Logger.ts`

### Media and IR

- [Camera streaming](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/util/TuyaStreamDelegate.ts): `src/util/TuyaStreamDelegate.ts`
- [Recording delegate](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/util/TuyaRecordingDelegate.ts): `src/util/TuyaRecordingDelegate.ts`
- [FFmpeg process](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/util/FfmpegStreamingProcess.ts): `src/util/FfmpegStreamingProcess.ts`
- [Infrared accessories](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/accessory/IRControlHubAccessory.ts): `src/accessory/IRControlHubAccessory.ts`
- [Infrared utilities](https://github.com/zalviandyr/homebridge-tuya/blob/latest/src/util/InfraredTool.ts): `src/util/InfraredTool.ts`

### Other components

- **Homebridge user**
- **Tuya Cloud**
- **HomeKit**

## Connections

- Homebridge user → Platform lifecycle: configures (evidence: `README.md`)
- Platform lifecycle → Config and overrides: validates (evidence: `src/platform.ts`)
- Platform lifecycle → Tuya HTTP API: creates (evidence: `src/platform.ts`)
- Platform lifecycle → Custom asset discovery: selects Custom (evidence: `src/platform.ts`)
- Platform lifecycle → Smart Home discovery: selects Smart Home (evidence: `src/platform.ts`)
- Platform lifecycle → Accessory factory: creates handlers (evidence: `src/platform.ts`)
- Smart Home discovery → Device operations: extends (evidence: `src/device/TuyaHomeDeviceManager.ts`)
- Custom asset discovery → Device operations: extends (evidence: `src/device/TuyaCustomDeviceManager.ts`)
- Custom asset discovery → Tuya HTTP API: queries assets (evidence: `src/device/TuyaCustomDeviceManager.ts`)
- Device operations → Tuya HTTP API: requests device data (evidence: `src/device/TuyaDeviceManager.ts`)
- Device operations → Tuya event MQTT: uses events (evidence: `src/device/TuyaDeviceManager.ts`)
- Device operations → Device and DP model: builds devices (evidence: `src/device/TuyaCustomDeviceManager.ts`)
- Tuya HTTP API → Tuya Cloud: sends HTTP (evidence: `README.md`)
- Tuya event MQTT → Tuya Cloud: connects MQTT (evidence: `README.md`)
- Accessory factory → Accessory state and commands: creates handlers (evidence: `src/accessory/AccessoryFactory.ts`)
- Accessory factory → Device category handlers: dispatches categories (evidence: `src/accessory/AccessoryFactory.ts`)
- Accessory state and commands → Device operations: sends commands (evidence: `src/accessory/BaseAccessory.ts`)
- Device category handlers → Accessory state and commands: specializes (evidence: `src/accessory/GarageDoorAccessory.ts`)
- Device category handlers → HomeKit characteristic mapping: configures (evidence: `src/accessory/AirConditionerAccessory.ts`)
- Accessory state and commands → HomeKit: updates state
- HomeKit → Accessory state and commands: sets characteristics
- Platform lifecycle → Tap-to-Run scenes: supports scenes (evidence: `README.md`)
- Camera accessory → Camera streaming: creates stream delegate (evidence: `src/accessory/CameraAccessory.ts`)
- Camera streaming → Recording delegate: uses (evidence: `src/util/TuyaStreamDelegate.ts`)
- Camera streaming → FFmpeg process: starts process (evidence: `src/util/TuyaStreamDelegate.ts`)
- Camera streaming → Tuya Cloud: requests video stream (evidence: `README.md`)
- Infrared accessories → Device operations: sends IR commands
- Infrared utilities → Infrared accessories: supports control
- Tuya HTTP API → Logging: logs (evidence: `src/core/TuyaOpenAPI.ts`)
- Device operations → Logging: logs (evidence: `src/device/TuyaDeviceManager.ts`)
