# zackwag/homebridge-somneo architecture

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

- Interactive diagram: https://gitdiagram.com/zackwag/homebridge-somneo
- Repository: https://github.com/zackwag/homebridge-somneo

## Overview

##### Project Type and Purpose
- This project is a Homebridge plugin for integrating the Philips Somneo HF3670/60 clock into the Homebridge ecosystem.
- Its purpose is to manage the clock’s multiple functionalities (lights, sensors, switches, and audio) by communicating via the clock’s internal HTTP server.
- Conflicting accessory management is an important domain concept, as the physical device is represented by several virtual accessories (e.g., main light, night light, sunset program, relax breathe program, and audio).

##### File Structure
- Notice that the top-level structure contains configuration files (e.g., package.json, tsconfig.json, .eslintrc) and a src directory which holds the TypeScript source code.
- Within the src folder, “index.ts” acts as the entry point, and the “lib” subdirectory contains files corresponding to different accessory implementations (e.g., somneoLightAccessory.ts, somneoAudioAccessory.ts, somneoSwitchAccessory.ts, etc.).
- Other files like "somneoPlatform.ts" and "userSettings.ts" suggest a separation between platform initialization, accessory management, and user configuration.
- The presence of configuration files related to GitHub actions and ESLint indicates continuous integration and adherence to code quality.

##### Additional Insights from the README
- The README explains the overall functioning of the plugin, the mapping of physical device elements to Homebridge accessories, and the configuration schema.
- It details manual and UI-based installation options, along with a detailed JSON configuration schema—indicating that configuration and customization are central to the plugin.
- The “Conflicting Accessories” table provided in the README is a crucial design element, showing how activation of one accessory may disable others (e.g., turning on the sunset program turns off certain light accessories and audio).

a. Main Components:
– Homebridge Environment: Represents the larger Homebridge ecosystem in which the plugin operates.
– HomebridgeSomneo Platform Module: This component (likely implemented in somneoPlatform.ts and index.ts) initializes and registers the various accessories with Homebridge.
– Accessories / Feature Modules: Separate components for handling different features—for example:
- Light Accessories (mainLight, nightLight)
- Sensor Accessories (temperature, humidity, lux)
- Switch Accessories (relaxBreathe, sunset)
- Audio Accessory (handled externally as outlined in the README)
– Configuration Layer: This involves the user settings and JSON schema-based configuration (userSettings.ts and config.schema.json) that dictate the behavior of each accessory.
– External Somneo Device: The physical Philips Somneo clock which hosts an HTTP API. This is the source of commands and sensor data.

b. Relationships and Interactions:
– The HomebridgeSomneo Platform Module receives configuration information (via config files) and instantiates the relevant accessory modules.
– Each accessory module communicates with the Somneo device via HTTP requests (see how “the clock has a small HTTP server running inside”) to both send commands (e.g., turning on/off lights, switches) and receive sensor data.
– The polling mechanism (driven by “pollingSeconds”) should be represented to show periodic communication with the Somneo device.

c. Architectural Patterns:
– The design showcases modularity and separation of concerns: each accessory is implemented as its own module.
– There is a clear transversal configuration layer which feeds into different components.
– The plugin adheres to the Homebridge platform’s model of plugin development, dynamically exposing multiple virtual accessories that map to a single physical device.
– It emphasizes a layered architecture: (configuration/UI) → (platform core) → (accessory handlers) → (device HTTP API integration).

d. Relevant Technologies and Frameworks:
– TypeScript is used throughout, so include a “TypeScript/Node.js” note.
– Homebridge’s API and plugin system is the backbone of the integration.
– HTTP communication (via the internal Somneo API) is crucial.
– Mention popular Node.js patterns such as module separation and callbacks/promise-based HTTP handling if relevant.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Homebridge Environment"
        HBEnv["Homebridge Environment"]:::homebridge
    end

    subgraph "Configuration Layer"
        Config["User Configuration<br/>(JSON Schema & Settings)"]:::config
    end

    subgraph "Platform Core"
        Platform["HomebridgeSomneo Platform"]:::platform
    end

    subgraph "Accessory Modules"
        MainLight["Main/Primary Light Accessory"]:::accessory
        NightLight["Night Light Accessory"]:::accessory
        ExtraLight["Additional Dimmable Light Accessory"]:::accessory
        GeneralSwitch["General Switch Accessory"]:::accessory
        SunsetSwitch["Sunset Switch Accessory"]:::accessory
        RelaxSwitch["Relax Breathe Switch Accessory"]:::accessory
        Sensor["Sensor Accessory<br/>(Temperature/Humidity)"]:::accessory
        Audio["Audio Accessory"]:::accessory
    end

    subgraph "External Somneo Device"
        Somneo["Somneo Device<br/>(HTTP API)"]:::external
    end

    %% Flows between layers
    HBEnv -->|"Contains"| Config
    Config -->|"ConfigurationFlow"| Platform

    Platform -->|"Initialize"| MainLight
    Platform -->|"Initialize"| NightLight
    Platform -->|"Initialize"| ExtraLight
    Platform -->|"Initialize"| GeneralSwitch
    Platform -->|"Initialize"| SunsetSwitch
    Platform -->|"Initialize"| RelaxSwitch
    Platform -->|"Initialize"| Sensor
    Platform -->|"Initialize"| Audio

    %% Communication from accessories to Somneo device
    MainLight -->|"CommandDispatch"| Somneo
    NightLight -->|"CommandDispatch"| Somneo
    ExtraLight -->|"CommandDispatch"| Somneo
    GeneralSwitch -->|"CommandDispatch"| Somneo
    SunsetSwitch -->|"CommandDispatch"| Somneo
    RelaxSwitch -->|"CommandDispatch"| Somneo
    Sensor -->|"PollingHTTPRequest"| Somneo
    Audio -->|"CommandDispatch"| Somneo

    %% Conflict control arrows between switches and lights
    SunsetSwitch -->|"conflictcontrol"| MainLight
    SunsetSwitch -->|"conflictcontrol"| NightLight
    RelaxSwitch -->|"conflictcontrol"| MainLight
    RelaxSwitch -->|"conflictcontrol"| NightLight

    %% Click Events
    click Platform "https://github.com/zackwag/homebridge-somneo/blob/master/src/index.ts"
    click Platform "https://github.com/zackwag/homebridge-somneo/blob/master/src/somneoPlatform.ts"
    click MainLight "https://github.com/zackwag/homebridge-somneo/blob/master/src/lib/somneoMainLightAccessory.ts"
    click NightLight "https://github.com/zackwag/homebridge-somneo/blob/master/src/lib/somneoNightLightAccessory.ts"
    click ExtraLight "https://github.com/zackwag/homebridge-somneo/blob/master/src/lib/somneoDimmableLightAccessory.ts"
    click GeneralSwitch "https://github.com/zackwag/homebridge-somneo/blob/master/src/lib/somneoSwitchAccessory.ts"
    click SunsetSwitch "https://github.com/zackwag/homebridge-somneo/blob/master/src/lib/somneoSunsetSwitchAccessory.ts"
    click RelaxSwitch "https://github.com/zackwag/homebridge-somneo/blob/master/src/lib/somneoRelaxBreatheSwitchAccessory.ts"
    click Sensor "https://github.com/zackwag/homebridge-somneo/blob/master/src/lib/somneoSensorAccessory.ts"
    click Audio "https://github.com/zackwag/homebridge-somneo/blob/master/src/lib/somneoAudioAccessory.ts"
    click Config "https://github.com/zackwag/homebridge-somneo/blob/master/src/lib/userSettings.ts"
    click Config "https://github.com/zackwag/homebridge-somneo/blob/master/config.schema.json"
    click Somneo "https://github.com/zackwag/homebridge-somneo/blob/master/src/lib/somneoClock.ts"

    %% Styles
    classDef homebridge fill:#fde2e2,stroke:#d71a1a,stroke-width:2px;
    classDef config fill:#ead1dc,stroke:#b85450,stroke-width:2px;
    classDef platform fill:#d9ead3,stroke:#0b5394,stroke-width:2px;
    classDef accessory fill:#cfe2f3,stroke:#1155cc,stroke-width:2px;
    classDef external fill:#fff2cc,stroke:#bf9000,stroke-width:2px;
```
