# koosoli/esphomedesigner architecture

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

- Interactive diagram: https://gitdiagram.com/koosoli/esphomedesigner
- Repository: https://github.com/koosoli/esphomedesigner

## Overview

ESPHome Designer is a browser-based, plugin-driven visual editor for smart-display layouts, usable standalone or through Home Assistant. Users arrange widgets on pages, configure properties and device settings, then export platform-specific output or save layouts; existing ESPHome, OEPL, and OpenDisplay configurations can be imported for round-trip editing. The frontend also supports AI-assisted layout generation and entity/MQTT data sources. The map combines README-documented capabilities with sampled frontend wiring and backend storage evidence; unsampled subsystem links are shown only where documented.

Main entry points: [`custom_components/esphome_designer/frontend/js/main.js`](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/main.js) (Editor runtime), [`custom_components/esphome_designer/frontend/js/ui/layout_manager_workflows.js`](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/ui/layout_manager_workflows.js) (Multi-page layouts), [`custom_components/esphome_designer/frontend/features`](https://github.com/koosoli/esphomedesigner/tree/main/custom_components/esphome_designer/frontend/features) (Widget plugins), [`custom_components/esphome_designer/frontend/js/ui/snippet_manager.js`](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/ui/snippet_manager.js) (YAML snippet editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editor["Visual editor"]
  node_app["Editor runtime<br/>[main.js]"]
  node_canvas["Canvas editor<br/>[canvas.js]"]
  node_palette["Widget palette<br/>[widget_palette.js]"]
  node_properties["Widget properties<br/>[properties.js]"]
  node_settings["Editor settings<br/>[editor_settings.js]"]
  node_worldview["Multi-page layouts"]
end

subgraph group_widgets["Widget system"]
  node_widgets["Widget plugins"]
  node_registry["Plugin registry<br/>[plugin_registry.js]"]
end

subgraph group_io["Import and export"]
  node_snippet["YAML snippet editor<br/>[snippet_manager.js]"]
  node_yamlimport["YAML import<br/>[yaml_import.ts]"]
  node_parser["Display parser<br/>[display_parser.js]"]
  node_export["Platform exporters"]
  node_ai["AI assistant<br/>[ai_service.js]"]
end

subgraph group_integration["Home Assistant integration"]
  node_ha["Home Assistant API<br/>[ha_api.js]"]
  node_backend["Integration API<br/>[http_api.py]"]
  node_services["HA services<br/>[services.py]"]
  node_storage[("Layout storage<br/>[storage.py]")]
end

subgraph group_state["Project state"]
  node_state["Editor state<br/>[index.ts]"]
  node_widgetstate["Widget manager<br/>[widget_manager.js]"]
  node_events["Event bus<br/>[events.js]"]
  node_models["Layout models<br/>[models.py]"]
end

node_user(("Designer user"))
node_ha_service(("Home Assistant"))
node_mqtt(("MQTT broker"))

node_user -->|"uses"| node_app
node_app -->|"initializes"| node_canvas
node_app -->|"renders"| node_palette
node_app -->|"initializes"| node_properties
node_app -->|"initializes"| node_settings
node_palette -.->|"discovers"| node_registry
node_registry -.->|"registers"| node_widgets
node_canvas -.->|"edits"| node_widgetstate
node_widgetstate -->|"emits changes"| node_events
node_state -->|"constructs"| node_widgetstate
node_user -->|"manages pages"| node_worldview
node_worldview -->|"requests layouts"| node_ha
node_worldview -->|"loads layout"| node_yamlimport
node_user -->|"edits YAML"| node_snippet
node_snippet -->|"generates snippet"| node_export
node_snippet -->|"imports YAML"| node_yamlimport
node_yamlimport -->|"parses display"| node_parser
node_user -->|"exports design"| node_export
node_user -->|"prompts layouts"| node_ai
node_user -->|"saves layouts"| node_ha
node_ha -->|"calls integration"| node_backend
node_backend -.->|"persists state"| node_storage
node_services -->|"reads and writes"| node_storage
node_storage -->|"persists models"| node_models
node_widgets -.->|"reads entity data"| node_ha_service
node_widgets -->|"reads topics"| node_mqtt
node_user -->|"integrates device"| node_ha_service

click node_app "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/main.js"
click node_canvas "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/core/canvas.js"
click node_palette "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/ui/widget_palette.js"
click node_properties "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/core/properties.js"
click node_settings "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/ui/editor_settings.js"
click node_widgets "https://github.com/koosoli/esphomedesigner/tree/main/custom_components/esphome_designer/frontend/features"
click node_registry "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/core/plugin_registry.js"
click node_worldview "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/ui/layout_manager_workflows.js"
click node_state "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/core/stores/index.ts"
click node_widgetstate "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/core/stores/app_state/widget_manager.js"
click node_events "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/core/events.js"
click node_snippet "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/ui/snippet_manager.js"
click node_yamlimport "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/io/yaml_import.ts"
click node_parser "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/io/yaml_parsers/display_parser.js"
click node_export "https://github.com/koosoli/esphomedesigner/tree/main/custom_components/esphome_designer/frontend/js/io/adapters"
click node_ai "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/io/ai_service.js"
click node_ha "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/io/ha_api.js"
click node_backend "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/http_api.py"
click node_services "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/services.py"
click node_storage "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/storage.py"
click node_models "https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/models.py"

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_app,node_canvas,node_palette,node_properties,node_settings,node_worldview,node_user toneBlue
class node_widgets,node_registry toneAmber
class node_snippet,node_yamlimport,node_parser,node_export,node_ai toneMint
class node_ha,node_backend,node_services,node_storage toneRose
class node_state,node_widgetstate,node_events,node_models,node_ha_service,node_mqtt toneIndigo
```

## Components

### Visual editor

- [Editor runtime](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/main.js): `custom_components/esphome_designer/frontend/js/main.js`
- [Canvas editor](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/core/canvas.js): `custom_components/esphome_designer/frontend/js/core/canvas.js`
- [Widget palette](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/ui/widget_palette.js): `custom_components/esphome_designer/frontend/js/ui/widget_palette.js`
- [Widget properties](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/core/properties.js): `custom_components/esphome_designer/frontend/js/core/properties.js`
- [Editor settings](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/ui/editor_settings.js): `custom_components/esphome_designer/frontend/js/ui/editor_settings.js`
- [Multi-page layouts](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/ui/layout_manager_workflows.js): `custom_components/esphome_designer/frontend/js/ui/layout_manager_workflows.js`

### Widget system

- [Widget plugins](https://github.com/koosoli/esphomedesigner/tree/main/custom_components/esphome_designer/frontend/features): `custom_components/esphome_designer/frontend/features`
- [Plugin registry](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/core/plugin_registry.js): `custom_components/esphome_designer/frontend/js/core/plugin_registry.js`

### Import and export

- [YAML snippet editor](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/ui/snippet_manager.js): `custom_components/esphome_designer/frontend/js/ui/snippet_manager.js`
- [YAML import](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/io/yaml_import.ts): `custom_components/esphome_designer/frontend/js/io/yaml_import.ts`
- [Display parser](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/io/yaml_parsers/display_parser.js): `custom_components/esphome_designer/frontend/js/io/yaml_parsers/display_parser.js`
- [Platform exporters](https://github.com/koosoli/esphomedesigner/tree/main/custom_components/esphome_designer/frontend/js/io/adapters): `custom_components/esphome_designer/frontend/js/io/adapters`
- [AI assistant](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/io/ai_service.js): `custom_components/esphome_designer/frontend/js/io/ai_service.js`

### Home Assistant integration

- [Home Assistant API](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/io/ha_api.js): `custom_components/esphome_designer/frontend/js/io/ha_api.js`
- [Integration API](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/http_api.py): `custom_components/esphome_designer/http_api.py`
- [HA services](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/services.py): `custom_components/esphome_designer/services.py`
- [Layout storage](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/storage.py): `custom_components/esphome_designer/storage.py`

### Project state

- [Editor state](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/core/stores/index.ts): `custom_components/esphome_designer/frontend/js/core/stores/index.ts`
- [Widget manager](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/core/stores/app_state/widget_manager.js): `custom_components/esphome_designer/frontend/js/core/stores/app_state/widget_manager.js`
- [Event bus](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/frontend/js/core/events.js): `custom_components/esphome_designer/frontend/js/core/events.js`
- [Layout models](https://github.com/koosoli/esphomedesigner/blob/main/custom_components/esphome_designer/models.py): `custom_components/esphome_designer/models.py`

### Other components

- **Designer user**
- **Home Assistant**
- **MQTT broker**

## Connections

- Designer user → Editor runtime: uses
- Editor runtime → Canvas editor: initializes (evidence: `custom_components/esphome_designer/frontend/js/main.js`)
- Editor runtime → Widget palette: renders (evidence: `custom_components/esphome_designer/frontend/js/main.js`)
- Editor runtime → Widget properties: initializes (evidence: `custom_components/esphome_designer/frontend/js/main.js`)
- Editor runtime → Editor settings: initializes (evidence: `custom_components/esphome_designer/frontend/js/main.js`)
- Widget palette → Plugin registry: discovers
- Plugin registry → Widget plugins: registers
- Canvas editor → Widget manager: edits
- Widget manager → Event bus: emits changes (evidence: `custom_components/esphome_designer/frontend/js/core/stores/app_state/widget_manager.js`)
- Editor state → Widget manager: constructs (evidence: `custom_components/esphome_designer/frontend/js/core/stores/index.ts`)
- Designer user → Multi-page layouts: manages pages
- Multi-page layouts → Home Assistant API: requests layouts (evidence: `custom_components/esphome_designer/frontend/js/ui/layout_manager_workflows.js`)
- Multi-page layouts → YAML import: loads layout (evidence: `custom_components/esphome_designer/frontend/js/ui/layout_manager_workflows.js`)
- Designer user → YAML snippet editor: edits YAML
- YAML snippet editor → Platform exporters: generates snippet (evidence: `custom_components/esphome_designer/frontend/js/ui/snippet_manager.js`)
- YAML snippet editor → YAML import: imports YAML
- YAML import → Display parser: parses display (evidence: `custom_components/esphome_designer/frontend/js/io/yaml_parsers/display_parser.js`)
- Designer user → Platform exporters: exports design
- Designer user → AI assistant: prompts layouts
- Designer user → Home Assistant API: saves layouts
- Home Assistant API → Integration API: calls integration
- Integration API → Layout storage: persists state
- HA services → Layout storage: reads and writes (evidence: `custom_components/esphome_designer/services.py`)
- Layout storage → Layout models: persists models (evidence: `custom_components/esphome_designer/storage.py`)
- Widget plugins → Home Assistant: reads entity data
- Widget plugins → MQTT broker: reads topics
- Designer user → Home Assistant: integrates device
