Skip to content

Architecture

Hassette connects Home Assistant to the automations app authors write. It receives events over a WebSocket and routes them through an event bus to subscribed handlers. Each app gets typed access to the Home Assistant API, entity states, and a scheduler.

Three concepts underpin everything: apps, events, and resources.

  • Apps run the automation logic. Each app subscribes to events, schedules tasks, and calls Home Assistant services.
  • Events describe what happened: a state change, a service call, a scheduled trigger, or a lifecycle transition.
  • Resources are the objects apps use to act: the bus, the scheduler, the API client, and the state cache (States).

Per-App Handles

Every App instance carries four of these resources as handles — the objects automation code calls directly.

  • Api calls Home Assistant services, reads and writes entity states, and sends WebSocket commands.
  • Bus delivers Home Assistant events (state changes, service calls, component loads) to subscribed handlers.
  • Scheduler runs functions at a specified time, after a delay, or on a recurring interval.
  • States returns the current state of any Home Assistant entity from a local in-memory cache.

Each handle is scoped to the app instance. Listeners registered on one app's Bus do not fire for another app. Jobs scheduled on one app's Scheduler cancel independently of all others.

flowchart TD
    subgraph app["App Instance"]
        APP["App"]
    end

    subgraph handles["Handles"]
        direction LR
        API[Api]
        BUS[Bus]
        SCHED[Scheduler]
        STATES[States]
    end

    APP --> API & BUS & SCHED & STATES

    style app fill:#e8f0ff,stroke:#6688cc
    style handles fill:#fff0e8,stroke:#cc8844
Hold "Ctrl" to enable pan & zoom

Topics

  • Apps: the App base class, lifecycle hooks (on_initialize, on_shutdown), and AppConfig.
  • Bus: subscribing to events, filtering, handler options.
  • Scheduler: triggers, job groups, jitter.
  • API: service calls, state reads, WebSocket commands.
  • States: state models, domain access, type conversion.
  • Configuration: Hassette and app configuration.
  • Web UI: browser-based monitoring and management.
  • System Internals: service lifecycle, startup sequence, and the internal tree of resources that backs the per-app handles.
  • API Reference: auto-generated reference for all public modules.
Advanced Topics