# Architecture

`Service.qml` owns exactly one helper daemon for the shell lifetime. The Python helper authenticates to `/api/websocket`, reads floor/area/device/entity registries, fetches initial `/api/states`, subscribes to `state_changed`, and atomically publishes sanitized JSON. `BarWidget.qml` hosts `Panel.qml`; the panel polls that local snapshot and sends actions through a user-only Unix socket.

Entities inherit a device area only when their own `area_id` is empty. Presence candidates rank by device class (`occupancy`, `presence`, `motion`) and then stable entity ID. A valid manual override wins. Rooms rank by occupied status, descending last-presence timestamp, then case-insensitive name. All areas are retained unless explicitly hidden.

The cached snapshot is non-secret. When disconnected, the last layout stays visible but `connected` is false and the panel disables controls. Live states are rebuilt after reconnect, preventing cached values from being presented as current.

All server-controlled input crosses explicit resource boundaries. REST responses, individual WebSocket frames, and complete WebSocket messages are limited to 8 MiB, and registry/state collections have domain-specific element ceilings. State updates are reduced to the attributes Homearchy uses, with bounded strings and lists, before retention. Snapshot JSON is streamed atomically under a 4 MiB limit. `homearchy read-state` opens only the same regular, non-symlinked inode with nonblocking/no-follow flags and returns a valid offline fallback on failure. `Panel.qml` wraps that reader in a one-second TERM-to-KILL deadline and renders remote values as plain text.

The daemon retains and reacts only to enabled entities assigned directly or through a device to a discovered area. Relevant state bursts are coalesced over 500 ms, identical bounded snapshots are not rewritten, and room last-seen timestamps change only on an unoccupied-to-occupied transition. This keeps presence responsive without turning high-volume Home Assistant event streams into continuous CPU and disk activity.