# maxgramser/homeassistant_espscreen architecture

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

- Interactive diagram: https://gitdiagram.com/maxgramser/homeassistant_espscreen
- Repository: https://github.com/maxgramser/homeassistant_espscreen

## Overview

Home Assistant ESP Screens combines an ESP Screen Manager app, a browser-based screen editor and firmware for touch panels. The main workflow is: an administrator configures a screen in the editor, saves and sends its layout through the manager, and the panel renders Home Assistant data and dispatches tile actions. The README also documents firmware installation and updates, alerts, camera cards, history, and on-screen settings. Some backend and firmware modules are represented by their exact tree paths; their internal wiring is not inferred where excerpts were unavailable.

Main entry points: [`screen_manager/app/server.py`](https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/server.py) (Manager server), [`components/smart_display/smart_display.h`](https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/smart_display/smart_display.h) (Display runtime), [`components/smart_display/runtime_tiles.h`](https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/smart_display/runtime_tiles.h) (Tile rendering), [`web/src/store.ts`](https://github.com/maxgramser/homeassistant_espscreen/blob/main/web/src/store.ts) (Editor state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editor["Screen editor"]
  node_webapp["Editor app<br/>[App.vue]"]
  node_editorstore["Editor state<br/>[store.ts]"]
  node_layoutmodel["Layout model<br/>[layout.ts]"]
  node_drag["Drag editing<br/>[drag.ts]"]
  node_layoutview["Layout view<br/>[LayoutView.vue]"]
  node_webapi["Editor API<br/>[api.ts]"]
end

subgraph group_manager["HA manager"]
  node_manager["Manager server<br/>[server.py]"]
  node_core["HA integration<br/>[core.py]"]
  node_catalogue["Entity catalogue<br/>[ha_catalogue.py]"]
  node_alerts["Alert handling<br/>[alert_layout.py]"]
  node_camera["Camera feeds<br/>[camera_feed.py]"]
  node_history["History cards<br/>[history_card.py]"]
  node_firmwaremgmt["Firmware management<br/>[firmware.py]"]
  node_updates["App updates<br/>[updates.py]"]
end

subgraph group_firmware["Panel firmware"]
  node_display["Display runtime<br/>[smart_display.h]"]
  node_runtime["Tile rendering<br/>[runtime_tiles.h]"]
  node_runtime_model["Runtime model<br/>[runtime_model.h]"]
  node_settings["Screen settings<br/>[settings_screen.h]"]
  node_camera_card["Camera card<br/>[camera_view.h]"]
  node_history_view["History view<br/>[history_view.h]"]
end

subgraph group_touch["Touch input"]
  node_touchdriver["Touch driver<br/>[xpt2046.cpp]"]
  node_screeninput["Screen input<br/>[screen_input.h]"]
end

node_admin(("Administrator"))
node_homeassistant(("Home Assistant"))
node_panel(("ESP touch panel"))

node_admin -->|"edits screens"| node_webapp
node_webapp -->|"selects view"| node_editorstore
node_layoutview -->|"arranges tiles"| node_layoutmodel
node_drag -->|"previews placement"| node_layoutmodel
node_drag -->|"updates layout"| node_editorstore
node_editorstore -->|"requests API"| node_webapi
node_webapi -->|"sends layout"| node_manager
node_manager -->|"uses HA data"| node_core
node_manager -->|"loads entities"| node_catalogue
node_homeassistant -->|"provides states and actions"| node_manager
node_manager -->|"handles alerts"| node_alerts
node_manager -->|"serves camera feeds"| node_camera
node_manager -->|"provides history data"| node_history
node_manager -->|"manages firmware"| node_firmwaremgmt
node_manager -->|"checks updates"| node_updates
node_firmwaremgmt -->|"installs firmware"| node_panel
node_manager -->|"sends layout and updates"| node_panel
node_panel -->|"runs firmware"| node_display
node_display -->|"renders tiles"| node_runtime
node_runtime -->|"reads screen model"| node_runtime_model
node_runtime -->|"dispatches tile actions"| node_homeassistant
node_display -->|"offers settings"| node_settings
node_display -->|"renders camera"| node_camera_card
node_display -->|"renders history"| node_history_view
node_touchdriver -->|"reports touch"| node_screeninput
node_screeninput -->|"routes input"| node_display

click node_webapp "https://github.com/maxgramser/homeassistant_espscreen/blob/main/web/src/App.vue"
click node_editorstore "https://github.com/maxgramser/homeassistant_espscreen/blob/main/web/src/store.ts"
click node_layoutmodel "https://github.com/maxgramser/homeassistant_espscreen/blob/main/web/src/model/layout.ts"
click node_drag "https://github.com/maxgramser/homeassistant_espscreen/blob/main/web/src/drag.ts"
click node_layoutview "https://github.com/maxgramser/homeassistant_espscreen/blob/main/web/src/components/LayoutView.vue"
click node_webapi "https://github.com/maxgramser/homeassistant_espscreen/blob/main/web/src/api.ts"
click node_manager "https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/server.py"
click node_core "https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/core.py"
click node_catalogue "https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/ha_catalogue.py"
click node_alerts "https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/alert_layout.py"
click node_camera "https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/camera_feed.py"
click node_history "https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/history_card.py"
click node_firmwaremgmt "https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/firmware.py"
click node_updates "https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/updates.py"
click node_display "https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/smart_display/smart_display.h"
click node_runtime "https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/smart_display/runtime_tiles.h"
click node_runtime_model "https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/smart_display/runtime_model.h"
click node_settings "https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/smart_display/settings_screen.h"
click node_camera_card "https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/smart_display/camera_view.h"
click node_history_view "https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/smart_display/history_view.h"
click node_touchdriver "https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/xpt2046/touchscreen/xpt2046.cpp"
click node_screeninput "https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/smart_display/screen_input.h"

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_webapp,node_editorstore,node_layoutmodel,node_drag,node_layoutview,node_webapi toneBlue
class node_manager,node_core,node_catalogue,node_alerts,node_camera,node_history,node_firmwaremgmt,node_updates toneAmber
class node_display,node_runtime,node_runtime_model,node_settings,node_camera_card,node_history_view toneMint
class node_touchdriver,node_screeninput toneRose
class node_admin,node_homeassistant,node_panel toneIndigo
```

## Components

### Screen editor

- [Editor app](https://github.com/maxgramser/homeassistant_espscreen/blob/main/web/src/App.vue): `web/src/App.vue`
- [Editor state](https://github.com/maxgramser/homeassistant_espscreen/blob/main/web/src/store.ts): `web/src/store.ts`
- [Layout model](https://github.com/maxgramser/homeassistant_espscreen/blob/main/web/src/model/layout.ts): `web/src/model/layout.ts`
- [Drag editing](https://github.com/maxgramser/homeassistant_espscreen/blob/main/web/src/drag.ts): `web/src/drag.ts`
- [Layout view](https://github.com/maxgramser/homeassistant_espscreen/blob/main/web/src/components/LayoutView.vue): `web/src/components/LayoutView.vue`
- [Editor API](https://github.com/maxgramser/homeassistant_espscreen/blob/main/web/src/api.ts): `web/src/api.ts`

### HA manager

- [Manager server](https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/server.py): `screen_manager/app/server.py`
- [HA integration](https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/core.py): `screen_manager/app/core.py`
- [Entity catalogue](https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/ha_catalogue.py): `screen_manager/app/ha_catalogue.py`
- [Alert handling](https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/alert_layout.py): `screen_manager/app/alert_layout.py`
- [Camera feeds](https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/camera_feed.py): `screen_manager/app/camera_feed.py`
- [History cards](https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/history_card.py): `screen_manager/app/history_card.py`
- [Firmware management](https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/firmware.py): `screen_manager/app/firmware.py`
- [App updates](https://github.com/maxgramser/homeassistant_espscreen/blob/main/screen_manager/app/updates.py): `screen_manager/app/updates.py`

### Panel firmware

- [Display runtime](https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/smart_display/smart_display.h): `components/smart_display/smart_display.h`
- [Tile rendering](https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/smart_display/runtime_tiles.h): `components/smart_display/runtime_tiles.h`
- [Runtime model](https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/smart_display/runtime_model.h): `components/smart_display/runtime_model.h`
- [Screen settings](https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/smart_display/settings_screen.h): `components/smart_display/settings_screen.h`
- [Camera card](https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/smart_display/camera_view.h): `components/smart_display/camera_view.h`
- [History view](https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/smart_display/history_view.h): `components/smart_display/history_view.h`

### Touch input

- [Touch driver](https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/xpt2046/touchscreen/xpt2046.cpp): `components/xpt2046/touchscreen/xpt2046.cpp`
- [Screen input](https://github.com/maxgramser/homeassistant_espscreen/blob/main/components/smart_display/screen_input.h): `components/smart_display/screen_input.h`

### Other components

- **Administrator**
- **Home Assistant**
- **ESP touch panel**

## Connections

- Administrator → Editor app: edits screens
- Editor app → Editor state: selects view
- Layout view → Layout model: arranges tiles
- Drag editing → Layout model: previews placement
- Drag editing → Editor state: updates layout
- Editor state → Editor API: requests API
- Editor API → Manager server: sends layout
- Manager server → HA integration: uses HA data
- Manager server → Entity catalogue: loads entities
- Home Assistant → Manager server: provides states and actions
- Manager server → Alert handling: handles alerts
- Manager server → Camera feeds: serves camera feeds
- Manager server → History cards: provides history data
- Manager server → Firmware management: manages firmware
- Manager server → App updates: checks updates
- Firmware management → ESP touch panel: installs firmware
- Manager server → ESP touch panel: sends layout and updates
- ESP touch panel → Display runtime: runs firmware
- Display runtime → Tile rendering: renders tiles
- Tile rendering → Runtime model: reads screen model
- Tile rendering → Home Assistant: dispatches tile actions
- Display runtime → Screen settings: offers settings
- Display runtime → Camera card: renders camera
- Display runtime → History view: renders history
- Touch driver → Screen input: reports touch
- Screen input → Display runtime: routes input