Interactive architecture map of Home Assistant — the open-source home automation platform. Covering the Core event bus, state machine, HASS OS, Supervisor, Add-ons, 2700+ integrations, MQTT, Zigbee/Z-Wave, automations engine, Lovelace dashboard, Companion app, Nabu Casa cloud, ESPHome, and energy monitoring.
Home Assistant is an open-source home automation platform founded by Paulus Schoutsen in 2013. It runs locally (typically on a Raspberry Pi or NUC), prioritizes privacy and local control, and supports an extraordinary breadth of smart home devices through its modular integration system. The project is backed by Nabu Casa, a company founded by the core team to provide optional cloud services.
Home Assistant Core is a Python 3 application built on asyncio. At its center are three fundamental systems: the Event Bus (pub/sub message backbone), the State Machine (entity state tracking), and the Service Registry (callable actions). Every integration, automation, and UI interaction flows through these primitives.
An in-process asyncio pub/sub system. All state changes, service calls, time events, and system signals are fired as events. Integrations and automations subscribe to specific event types. The bus decouples producers from consumers, enabling the plugin architecture.
Tracks the current state of every entity in the system (lights, sensors, switches, etc.). Each state has an entity_id, state value, attributes dict, and last_changed/last_updated timestamps. State changes fire state_changed events on the bus.
Registry of callable services organized by domain (e.g., light.turn_on, climate.set_temperature). Integrations register services; automations, scripts, and the UI invoke them. Services accept structured data and execute asynchronously.
Persistent registry mapping integration-provided unique IDs to user-facing entity_ids. Handles entity renaming, disabling, area assignment, and platform lifecycle. Stored in .storage/core.entity_registry as JSON.
The UI-driven configuration system. Each integration instance creates a config entry with its setup data. Entries support reload, reconfigure, and discovery flows. Replaces older YAML-based configuration for supported integrations.
SQLAlchemy-based persistence layer that records state changes to a database (SQLite by default, PostgreSQL/MariaDB supported). Powers the history graphs, logbook, and long-term statistics. Runs in a separate thread to avoid blocking the event loop.
Home Assistant follows a "local first" philosophy. All processing runs on local hardware, data stays on your network, and cloud connectivity is entirely optional. The core is designed to work even when internet access is unavailable — a critical requirement for a home automation system that controls physical infrastructure.
Home Assistant Operating System (HASS OS) is a minimal Linux distribution purpose-built for running Home Assistant. The Supervisor is a Docker-based orchestrator that manages the Core container, Add-ons, updates, backups, and system health — providing an appliance-like experience.
A Buildroot-based Linux distribution optimized for home automation appliances. Minimal footprint, OTA updates via RAUC, NetworkManager for networking, systemd for service management. Supports Raspberry Pi, ODROID, Intel NUC, and VMs (QEMU/VirtualBox/Hyper-V).
Python-based container orchestrator that manages Docker containers for Core, Add-ons, and system services. Handles automated updates, snapshot/backup management, hardware discovery (USB, GPIO, Bluetooth), and health monitoring. Exposes a REST API for the UI.
Docker containers managed by the Supervisor that extend system functionality. Examples: Mosquitto MQTT broker, MariaDB, VS Code Server, Zigbee2MQTT, Node-RED, Samba, DuckDNS. Add-ons can expose ports, use hardware, and communicate with Core via its API.
Full and partial backup system managed by the Supervisor. Creates tar archives of configuration, database, Add-on data, and secrets. Supports scheduled automated backups and one-click restore. Backups can be uploaded to cloud storage via Add-ons.
Integrations are the plugin system of Home Assistant. Each integration lives in its own Python package under homeassistant/components/ and provides entities (sensors, switches, lights, etc.) by communicating with devices or services. With 2700+ official integrations and thousands of custom ones via HACS, HA supports nearly every smart home device on the market.
Integrations implement async_setup_entry() for config-entry-based setup. They create platform entities, register services, subscribe to events, and set up device connections. Integrations can be loaded, unloaded, and reloaded at runtime without restarting Core.
UI-driven setup wizard system. Integrations define multi-step forms using config_flow.py with data schemas. Supports autodiscovery (mDNS/SSDP/USB), user input, OAuth2, and reauth flows. Each completed flow creates a config entry.
Home Assistant Community Store — a meta-integration that manages custom integrations, Lovelace cards, themes, and Python scripts from GitHub repositories. Provides a UI for browsing, installing, and updating community-maintained components.
Standardized entity types: Light, Switch, Sensor, Binary Sensor, Climate, Cover, Media Player, Camera, Lock, Vacuum, Fan, Number, Select, Button, and more. Each platform defines a base class with standard attributes and services that integrations implement.
Home Assistant rates integrations on a quality scale from "no score" through Bronze, Silver, Gold, to Platinum. Higher tiers require config flow support, test coverage, diagnostics, entity translation, device actions, and strict adherence to architectural guidelines. This drives consistent quality across the ecosystem.
Home Assistant communicates with smart home devices through multiple protocol stacks. MQTT provides lightweight pub/sub messaging, Zigbee and Z-Wave handle mesh networking for battery-powered sensors, and newer protocols like Matter/Thread aim to unify the ecosystem. ESPHome compiles custom firmware for ESP32/ESP8266 microcontrollers.
Lightweight publish/subscribe messaging protocol. HA includes a native MQTT integration and typically uses the Mosquitto Add-on as broker. MQTT Discovery allows devices to self-register with HA by publishing config topics. Widely used by DIY and commercial IoT devices.
Low-power mesh networking protocol (IEEE 802.15.4). Supported via ZHA (Zigbee Home Automation, native integration using zigpy) or Zigbee2MQTT (bridge via MQTT). Requires a USB coordinator (ConBee, Sonoff, SLZB). Supports 100s of device types from Aqara, IKEA, Hue, Sonoff, etc.
Z-Wave protocol support via the Z-Wave JS project. Runs a Z-Wave JS Server as an Add-on or external service, communicating over WebSockets. Provides comprehensive device support, OTA firmware updates, S2 security, and SmartStart provisioning.
Framework for ESP32/ESP8266/RP2040 microcontrollers. Users define device behavior in YAML, ESPHome compiles and flashes custom C++ firmware. Native API integration with HA provides encrypted, low-latency communication. Used for DIY sensors, displays, LED controllers, and more.
Next-generation smart home standard backed by Apple, Google, Amazon, and Samsung. Thread provides the IPv6 mesh network layer; Matter defines the application protocol. HA includes a Matter Server integration for local control of Matter-certified devices.
Primary real-time API for the frontend and external clients. Provides authenticated bidirectional communication for state subscriptions, service calls, event listening, and admin operations. Powers the Lovelace dashboard and Companion apps.
The automations engine is the intelligence layer of Home Assistant. Automations follow a Trigger-Condition-Action model: triggers fire on events (state changes, time, device events), conditions gate execution (time of day, entity states, zones), and actions execute services (turn on lights, send notifications, call scripts).
Event sources that start an automation: state changes, numeric state thresholds, time patterns, sunrise/sunset, zone entry/exit, device triggers, webhook, MQTT messages, calendar events, and template conditions becoming true.
Boolean gates evaluated before actions run: state conditions, numeric state, time windows, zone presence, template evaluation, and/or/not logic. If any condition fails, the automation stops without executing actions.
Sequences of service calls, delays, conditions, choose/if-then, repeat loops, parallel execution, and variable assignment. Scripts are reusable action sequences. Actions can target specific entities, areas, or device groups.
Sharable automation templates. A blueprint defines the automation structure with configurable inputs (entity selectors, number sliders, etc.). Users instantiate blueprints without writing YAML. Community blueprints are shared via the Blueprint Exchange forum.
Jinja2 templates power dynamic values throughout HA: automation conditions, sensor definitions, notification messages, dashboard cards. Templates can access all entity states, call math functions, format dates, and evaluate complex logic.
Snapshots of desired entity states. A scene captures light brightness/color, thermostat settings, cover positions, etc. Activating a scene applies all captured states simultaneously. Can be created from the UI or defined in YAML.
Each automation has a mode controlling concurrency: single (skip if already running), restart (cancel previous and start fresh), queued (queue and run sequentially), or parallel (run all instances simultaneously). This prevents race conditions when triggers fire rapidly.
Lovelace is the customizable dashboard system for Home Assistant. Built as a modern web application using Lit (Web Components), it provides a rich library of cards for controlling devices, visualizing data, and displaying camera feeds. Dashboards are defined in YAML or configured visually through the UI editor.
Single-page application built with Lit web components. Communicates with HA Core via WebSocket API for real-time state updates. Supports multiple dashboards, views (tabs), and responsive layout with masonry or grid modes.
Modular card components: entities, buttons, gauges, graphs, weather, map, media control, thermostat, light, alarm panel, and more. Custom cards from HACS extend the library with 3D floorplans, calendars, vacuum maps, and advanced visualizations.
CSS variable-based theming system. Themes override 50+ CSS variables controlling colors, fonts, borders, and shadows. Applied globally or per-dashboard. Community themes provide Material Design, iOS-inspired, dark, neon, and minimal aesthetics.
Drag-and-drop dashboard editor built into the UI. Add, remove, and configure cards without editing YAML. Supports sections layout (grid-based), conditional cards, badges, and header/footer widgets. Power users can switch to raw YAML mode.
The official Companion App for iOS and Android extends Home Assistant beyond the local network. It provides location tracking, push notifications, device sensors (battery, connectivity, steps), and widgets. The app connects to HA Core via the WebSocket API, either directly on the local network or through Nabu Casa remote access.
The app exposes 30+ device sensors to HA: battery level, charging state, WiFi SSID, Bluetooth, steps, screen brightness, storage, audio volume, and more. These become entities in HA usable in automations (e.g., "if phone battery below 20%, turn on charger").
GPS-based device tracking with configurable accuracy and update intervals. Creates device_tracker entities for presence detection. Integrates with HA zones for "person entered home" / "person left work" automations.
Push notification service with rich features: images, action buttons, critical alerts (bypass DND), notification groups, clearing, and replacement. Supports Android-specific channels and iOS-specific categories. The primary way HA alerts users to events.
Nabu Casa provides optional cloud services that complement local Home Assistant installations. Founded by the HA core team, the $7.50/month subscription funds full-time development. Cloud services include secure remote access (no port forwarding), Google Assistant and Alexa voice integrations, and cloud-based text-to-speech.
Encrypted tunnel via Nabu Casa's relay infrastructure. No port forwarding, dynamic DNS, or SSL certificate management needed. Uses a unique subdomain (*.ui.nabu.casa) with automatic TLS. Traffic is relayed but end-to-end encrypted.
Cloud bridges for Google Assistant and Amazon Alexa. Exposes HA entities as smart home devices to voice platforms. Supports on/off, brightness, color, temperature, locks, covers, and media control. No custom Actions/Skills setup required.
Cloud-based text-to-speech and speech-to-text services. TTS converts text notifications to spoken audio on media players. STT enables the local voice assistant pipeline (Assist) to use cloud-based speech recognition as an alternative to local Whisper.
HA's own voice assistant framework. Fully local pipeline: Wake word (openWakeWord) → STT (Whisper) → Intent recognition (HA Intents) → TTS (Piper). Can run entirely on local hardware with no cloud dependency. Supports custom sentences and languages.
In 2023, Home Assistant declared "Year of the Voice" and invested heavily in building a fully local voice assistant stack. The Assist pipeline, powered by Whisper (STT), Piper (TTS), and openWakeWord, can run entirely on a Raspberry Pi 4 or better — providing voice control without any cloud dependency.
The Energy Dashboard is a first-class feature in Home Assistant for tracking electricity consumption, solar production, gas usage, and water consumption. It integrates with smart meters, CT clamp sensors, solar inverters, and utility APIs to provide detailed breakdowns of energy usage per device and cost calculations.
Dedicated dashboard showing daily/weekly/monthly energy usage with stacked bar charts. Breaks down consumption by individual devices, compares grid vs. solar usage, tracks costs with configurable tariffs, and shows self-sufficiency percentage.
The statistics engine compiles 5-minute aggregates (min/max/mean/sum) from raw sensor data. These are stored efficiently and kept indefinitely, even as detailed history is purged. Powers the energy dashboard, trend analysis, and history graphs with years of data.
Supports utility smart meters (P1, DSMR), whole-home CT clamp monitors (Emporia Vue, Shelly EM, IoTaWatt), solar inverters (Enphase, SolarEdge, Fronius), and individual device power monitors (smart plugs with energy metering).