# nitaybz/homebridge-tami4 architecture

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

- Interactive diagram: https://gitdiagram.com/nitaybz/homebridge-tami4
- Repository: https://github.com/nitaybz/homebridge-tami4

## Overview

##### Project type and purpose
- This is a Node.js “platform” plugin for the [Homebridge](https://github.com/nfarina/homebridge) ecosystem, named **homebridge-tami4**. Its purpose is to expose a Tami4 Edge+ water purifier’s capabilities (lighting, heating, night mode, etc.) as HomeKit accessories.

##### File structure
Top-level files
- `index.js` – Plugin entry point: registers the “Tami4” platform with Homebridge.
- `config-sample.json` & `config.schema.json` – Sample and JSON-schema for plugin configuration (refreshToken, feature flags, polling interval, debug).

Directories
- `homebridge-ui/`
– `server.js` – Express‐style server to serve plugin settings UI inside Homebridge/Hoobs.
– `public/index.html` – React/vanilla HTML UI shell for collecting `refreshToken` & settings.

- `homekit/`
– `StateManager.js` – Caches and normalizes Tami4 state, debounces HomeKit updates.
– `device.js` – Constructs HomeKit switch/accessory objects, implements the HomeKit API handlers.

- `tami4/`
– `api.js` – Wraps REST calls to Tami4 Edge cloud (login, device status, control commands).
– `syncHomeKitCache.js` – Sync logic between remote cloud state and local HomeKit state cache.

##### README for additional insights
- The plugin “platform” polls Tami4 Edge cloud at a configurable interval (`statePollingInterval`) using a long-lived `refreshToken`.
- Incoming state updates drive HomeKit accessory updates. User actions in HomeKit translate to REST calls back to the Tami4 cloud.
- The Homebridge UI plugin portion is responsible only for obtaining and storing the `refreshToken` and initial plugin settings.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User & UI Layer
    User["User"]:::ui
    SettingsFrontend["Settings Frontend"]:::ui
    SettingsServer["Settings Server"]:::ui
    ConfigSample["config-sample.json"]:::core
    ConfigSchema["config.schema.json"]:::core
    ConfigStore["Homebridge Config Store\n(config.json)"]:::core

    %% Homebridge Core
    HomebridgeCore["Homebridge Core"]:::core

    %% Plugin Backend Layer
    subgraph "Plugin Backend" 
        direction TB
        Tami4API["Tami4 API Layer"]:::backend
        StateSync["State Synchronizer"]:::backend
        StateManager["StateManager (Cache & Debounce)"]:::backend
        AccessoryFactory["HomeKit Accessory Factory"]:::backend
    end

    %% HomeKit Framework
    HomeKitFW["HomeKit Framework"]:::core

    %% External Services
    subgraph "External" 
        direction TB
        Tami4Cloud["Tami4 Edge Cloud"]:::external
        PhysicalDevice["Physical Tami4 Device"]:::external
    end

    %% Flows
    User -->|"opens UI"| SettingsFrontend
    SettingsFrontend -->|"submit settings"| SettingsServer
    SettingsServer -->|"write refreshToken & flags"| ConfigStore
    SettingsFrontend --> SettingsServer
    SettingsServer --> ConfigSample
    SettingsServer --> ConfigSchema

    HomebridgeCore -->|"load plugin\n(index.js)"| ConfigStore
    HomebridgeCore --> PluginBackend
    PluginBackend --> Tami4API
    Tami4API -->|"HTTPS REST calls"| Tami4Cloud
    Tami4Cloud --> PhysicalDevice
    PhysicalDevice --> Tami4Cloud
    Tami4Cloud -->|"state response"| StateSync
    StateSync --> StateManager
    StateManager --> AccessoryFactory
    AccessoryFactory --> HomeKitFW
    HomeKitFW --> HomebridgeCore

    HomeKitFW -->|"user action event"| AccessoryFactory
    AccessoryFactory --> Tami4API

    %% Click Events
    click SettingsFrontend "https://github.com/nitaybz/homebridge-tami4/blob/master/homebridge-ui/public/index.html"
    click SettingsServer "https://github.com/nitaybz/homebridge-tami4/blob/master/homebridge-ui/server.js"
    click Tami4API "https://github.com/nitaybz/homebridge-tami4/blob/master/tami4/api.js"
    click StateSync "https://github.com/nitaybz/homebridge-tami4/blob/master/tami4/syncHomeKitCache.js"
    click StateManager "https://github.com/nitaybz/homebridge-tami4/blob/master/homekit/StateManager.js"
    click AccessoryFactory "https://github.com/nitaybz/homebridge-tami4/blob/master/homekit/device.js"
    click HomebridgeCore "https://github.com/nitaybz/homebridge-tami4/blob/master/index.js"
    click ConfigSchema "https://github.com/nitaybz/homebridge-tami4/blob/master/config.schema.json"
    click ConfigSample "https://github.com/nitaybz/homebridge-tami4/blob/master/config-sample.json"

    %% Styles
    classDef ui fill:#e5ffe5,stroke:#2d7f2d
    classDef backend fill:#e0f0ff,stroke:#1951a3
    classDef external fill:#ffe0b3,stroke:#aa5500
    classDef core fill:#eeeeee,stroke:#666666,stroke-dasharray: 2 2
```
