# pkozul/ha-floorplan architecture

> Architecture diagram of the GitHub repository pkozul/ha-floorplan, 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/pkozul/ha-floorplan
- Repository: https://github.com/pkozul/ha-floorplan

## Overview

##### Project Type and Purpose
- This is a Home Assistant **UI extension plugin** that embeds a custom SVG‐based floorplan into the Home Assistant frontend, exposing Home Assistant entities (binary sensors, lights, cameras, etc.) in a visual layout.
- It hooks into Home Assistant either as a **custom state card** or a **custom panel**, using a combination of JavaScript, SVG, CSS, and YAML configuration.

##### File Structure
- Top‐level YAMLs (`configuration.yaml`, `binary_sensors.yaml`, `customize.yaml`, `floorplan.yaml`, `panel_custom.yaml`) define Home Assistant’s core configuration, virtual sensors, custom panel/state‐card registration, and Floorplan‐specific settings.
- `www/custom_ui/floorplan` holds static frontend assets:
- `ha-floorplan.html` – main floorplan widget
- `floorplan.css` – styling for SVG and entity states
- `floorplan.svg` – the user’s custom vector floorplan
- `lib/` – JavaScript dependencies (`jquery`, `moment`, `svg-pan-zoom`)
- `www/custom_ui/state-card-floorplan.html` registers the floorplan as a **custom state card**.
- `panels/floorplan.html` registers the floorplan as a **panel_custom** when you want a full‐window view.

##### README Insights
- Shows two integration modes (state‐card vs. panel_custom).
- Describes loading order, YAML includes, available configuration options (pan/zoom, hide toolbar, last‐motion tracking, CSS‐based styling, actions on click).
- Explains the plugin’s runtime behavior: loading the SVG, mapping SVG element IDs to entity IDs, listening to real‐time state changes over Home Assistant’s WebSocket API, and dispatching service calls for clicks.

##### Main Components and Their Interactions
a. **Home Assistant Backend**
- Loads `configuration.yaml`, includes virtual binary_sensor (for state‐card), panel_custom entries, and the `floorplan.yaml` config.
- Exposes a WebSocket/REST API for state changes and service calls.
b. **Static Asset Server**
- Serves `ha-floorplan.html`, `state-card-floorplan.html`, `floorplan.css`, `floorplan.svg`, and JS libraries from `/local/custom_ui/...`.
c. **Browser Frontend**
- Fetches the appropriate HTML (panel or state‐card), CSS, JS, and SVG.
- Initializes the Floorplan JS widget, connects to the Home Assistant WebSocket, queries initial entity states.
d. **SVG Floorplan**
- Defines `<path>`, `<rect>`, `<text>`, etc., each with `id="entity_id"` linking to Home Assistant entity states.
- Acts as the view layer that gets updated dynamically.
e. **JavaScript Libraries & Floorplan Code**
- `jquery`/`moment`/`svg-pan-zoom` handle DOM manipulation, timestamps, and interactive pan/zoom.
- The plugin’s main script reads `floorplan.yaml` (via `config:` include), applies CSS classes based on entity states, handles click events, and issues service calls back to the backend.
f. **Home Assistant State Machine & Integrations**
- Underlying integrations (e.g., MQTT, template sensors) supply entity states that feed the floorplan.

##### Architectural Patterns & Design Principles
- **Plugin Architecture**: The project is a drop‐in extension that follows Home Assistant’s custom_ui and panel_custom interfaces.
- **Model–View Binding**: Entities (model) drive SVG element classes/attributes (view) via real‐time WebSocket updates.
- **Configuration‐Driven Behavior**: All runtime behavior (styles, actions, panning) is driven by `floorplan.yaml`.
- **Separation of Concerns**:
- Backend persists states & runs integrations
- Frontend only renders and dispatches service calls
- SVG/CSS handle visuals
- YAML handles configuration

##### Detail to Capture
- YAML config inclusion (`!include floorplan.yaml`) and registration entries in `configuration.yaml` and `panel_custom.yaml`.
- How SVG element IDs map 1:1 to Home Assistant entity IDs.
- JS library responsibilities.
- Real‐time update cycle: Backend → WebSocket → JS → SVG/CSS.
- Click action cycle: SVG → JS → WebSocket → Backend service call → Entity state change.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Backend Components
    subgraph "Home Assistant Backend" 
        direction TB
        HAMain["Home Assistant Core"]:::server
        Configuration["configuration.yaml"]:::yaml
        BinarySensors["binary_sensors.yaml"]:::yaml
        Customize["customize.yaml"]:::yaml
        FloorplanYAML["floorplan.yaml"]:::yaml
        PanelCustomYAML["panel_custom.yaml"]:::yaml
        Entities["HA Integrations/Entities"]:::data
    end

    %% Static Asset Server
    subgraph "Static Asset Server" 
        direction TB
        AssetsDir["/local/custom_ui/floorplan/"]:::server
    end

    %% Browser Frontend Components
    subgraph "Browser Frontend" 
        direction TB
        StateCard["state-card-floorplan.html"]:::html
        Panel["floorplan.html (Panel)"]:::html
        FloorplanWidget["ha-floorplan.html"]:::html
        CSS["floorplan.css"]:::css
        SVG["floorplan.svg"]:::svg
        JSLibs["lib/"]:::lib
        FloorplanJS["Floorplan JS Widget"]:::js
    end

    %% Data Flows
    AssetsDir -->|HTTP| StateCard
    AssetsDir -->|HTTP| Panel
    AssetsDir -->|HTTP| FloorplanWidget
    AssetsDir -->|HTTP| CSS
    AssetsDir -->|HTTP| SVG
    AssetsDir -->|HTTP| JSLibs

    StateCard --> FloorplanJS
    Panel --> FloorplanJS
    FloorplanWidget --> FloorplanJS
    CSS --> FloorplanJS
    SVG --> FloorplanJS
    JSLibs --> FloorplanJS

    HAMain -->|WebSocket State Update| FloorplanJS
    FloorplanJS -->|WebSocket Subscribe/Service Call| HAMain
    HAMain -->|Updates from Integrations| Entities

    FloorplanJS -->|Manipulates| SVG

    %% Click Events
    click Configuration "https://github.com/pkozul/ha-floorplan/blob/master/configuration.yaml"
    click BinarySensors "https://github.com/pkozul/ha-floorplan/blob/master/binary_sensors.yaml"
    click Customize "https://github.com/pkozul/ha-floorplan/blob/master/customize.yaml"
    click FloorplanYAML "https://github.com/pkozul/ha-floorplan/blob/master/floorplan.yaml"
    click PanelCustomYAML "https://github.com/pkozul/ha-floorplan/blob/master/panel_custom.yaml"
    click AssetsDir "https://github.com/pkozul/ha-floorplan/tree/master/www/custom_ui/floorplan/"
    click FloorplanWidget "https://github.com/pkozul/ha-floorplan/blob/master/www/custom_ui/floorplan/ha-floorplan.html"
    click CSS "https://github.com/pkozul/ha-floorplan/blob/master/www/custom_ui/floorplan/floorplan.css"
    click JSLibs "https://github.com/pkozul/ha-floorplan/tree/master/www/custom_ui/floorplan/lib/"
    click StateCard "https://github.com/pkozul/ha-floorplan/blob/master/www/custom_ui/state-card-floorplan.html"
    click Panel "https://github.com/pkozul/ha-floorplan/blob/master/panels/floorplan.html"

    %% Styles
    classDef server fill:#a2c4c9,stroke:#333,stroke-width:1px;
    classDef yaml fill:#fce5cd,stroke:#333,stroke-width:1px;
    classDef html fill:#d9ead3,stroke:#333,stroke-width:1px;
    classDef css fill:#d0e0e3,stroke:#333,stroke-width:1px;
    classDef svg fill:#b6d7a8,stroke:#333,stroke-width:1px;
    classDef lib fill:#ffe599,stroke:#333,stroke-width:1px;
    classDef js fill:#f9cb9c,stroke:#333,stroke-width:1px;
    classDef data fill:#c9daf8,stroke:#333,stroke-width:1px;
```
