# koenkk/zigbee2mqtt architecture

> Architecture diagram of the GitHub repository koenkk/zigbee2mqtt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/koenkk/zigbee2mqtt
- Repository: https://github.com/koenkk/zigbee2mqtt

## Overview

##### Project Type and Purpose
- This project is a middleware or bridge application. Its main purpose is to allow end users to control and interact with their Zigbee devices without needing the vendor’s proprietary gateway. It converts Zigbee communication into MQTT messages for easy integration with smart home systems.
- The README clearly explains that it “bridges events” – meaning there is a significant emphasis on translating and mapping data between Zigbee networks and MQTT-based systems.

##### File Structure
- Top-level Files and Directories: The presence of files like cli.js, index.js, and extensive directories such as lib/, data/, docker/, and test/ indicates a well modularized project.
- The lib/ directory encompasses many separate modules. For example:
- The “controller”, “eventBus,” and “zigbee” modules handle core functionality.
- An “extension” subdirectory under lib/ contains many files like availability.ts, bind.ts, bridge.ts, etc. This indicates a plugin-like architecture that modularizes features such as device availability monitoring, binding operations, configuration, OTA updates, and more.
- The “model” directory encapsulates data structures for devices and groups.
- The “mqtt.ts” file suggests that the project handles MQTT communication directly.
- Utility modules (in lib/util) provide helper functions, configuration schema validation, logging, YAML-configuration handling, and settings migration.
- Other directories reveal support for Docker deployments, GitHub workflows for CI/CD, and scripts for building, testing, and generating changes. This reinforces that the project is deployed in containerized environments and embraces modern development practices.

##### README for Additional Insights
- The README highlights the three-tier internal architecture:
a. The hardware adapter layer (handled by the separate zigbee-herdsman project) connects to the physical Zigbee adapter.
b. The converters layer (zigbee-herdsman-converters) maps device-specific models and clusters.
c. The Zigbee2MQTT layer itself drives the herdsman, translates Zigbee messages to MQTT, and maintains device state (e.g., within the database file not directly visible in the tree but referenced in the docs).
- Integrations and support for multiple platforms (Home Assistant, Homey, Domoticz, etc.) should be represented, typically as external systems interfacing via MQTT.

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Systems
    subgraph "External Systems"
        A["Zigbee Adapter (zigbee-herdsman)"]:::external
        C["Conversion Layer (zigbee-herdsman-converters)"]:::external
        B["MQTT Broker (External)"]:::external
    end

    %% Core System
    subgraph "Core System"
        D["Application Core (Zigbee2MQTT)"]:::core
        E["MQTT Communication Module"]:::core
        F["Extensions/Plugins"]:::core
        G["CLI & API Interface"]:::core
        H["Device & Group Data Models"]:::core
        I["Utility Functions & Helpers"]:::core
        J["Device Database (Persistent JSON)"]:::core
    end

    %% Deployment & CI
    subgraph "Deployment & CI"
        K["Docker Container (Deployment)"]:::deploy
        L["CI/CD & Code Quality"]:::deploy
    end

    %% Relationships
    A -->|"zigbee_events"| C
    C -->|"data_conversion"| D
    G -->|"CLI_commands"| D
    D -->|"plugin_integration"| F
    D -->|"uses_models"| H
    D -->|"uses_utilities"| I
    D -->|"updates_state"| J
    D -->|"publish_MQTT"| E
    E -->|"MQTT_Messages"| B
    K -->|"deploys_to"| D
    L -->|"code_quality"| D

    %% Click Events for Component Mapping
    click D "https://github.com/koenkk/zigbee2mqtt/blob/master/index.js"
    click D "https://github.com/koenkk/zigbee2mqtt/blob/master/lib/controller.ts"
    click D "https://github.com/koenkk/zigbee2mqtt/blob/master/lib/zigbee.ts"
    click D "https://github.com/koenkk/zigbee2mqtt/blob/master/lib/state.ts"
    click G "https://github.com/koenkk/zigbee2mqtt/blob/master/cli.js"
    click E "https://github.com/koenkk/zigbee2mqtt/blob/master/lib/mqtt.ts"
    click F "https://github.com/koenkk/zigbee2mqtt/tree/master/lib/extension"
    click H "https://github.com/koenkk/zigbee2mqtt/tree/master/lib/model"
    click I "https://github.com/koenkk/zigbee2mqtt/tree/master/lib/util"
    click K "https://github.com/koenkk/zigbee2mqtt/tree/master/docker"
    click L "https://github.com/koenkk/zigbee2mqtt/tree/master/.github/workflows"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef core fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef deploy fill:#FFD700,stroke:#333,stroke-width:2px;
```
