Home Assistant Architecture Explained, Every Layer You Need to Know

Home Assistant powers over 700,000 active installations as of 2026, according to the project's own analytics, yet most users treat it as a black box. You click a button, a light turns on. Magic. But when something breaks at 2 AM, "magic" isn't helpful. Knowing the architecture tells you exactly where to look. We dive through each layer below.

Home Assistant overview for newcomers

TL;DR: Home Assistant is a four-layer stack: HA OS at the bottom, the Supervisor managing containers above it, HA Core handling automations and state in the middle, and Add-ons running alongside as isolated Docker containers. All processing happens locally. According to the Home Assistant analytics dashboard (2026), 68% of installations run HA OS, the full-stack version. Understanding each layer cuts troubleshooting time dramatically.

What Does the Layered Architecture Actually Look Like?

The full Home Assistant stack has four distinct layers, and each one has a specific job. Home Assistant OS (formerly HassOS) is the host operating system, a stripped-down Alpine Linux with nothing extra. The Supervisor runs directly on top of it, managing containers. HA Core is the Python application that handles all the smart home logic. Add-ons are separate Docker containers for auxiliary services.

Why build it this way? Because separating concerns makes everything safer. An add-on crash doesn't take down HA Core. A Core update doesn't touch the OS. You can update one layer without touching the others. It's the same principle Docker uses in production environments, and it works just as well here.

How Does the Supervisor Manage Everything?

The Supervisor (running as a Docker container itself, on image ghcr.io/home-assistant/amd64-hassio-supervisor) is the layer most users never think about. It handles OS updates, HA Core updates, add-on installation and lifecycle, snapshot/backup creation, and watchdog monitoring. If HA Core crashes, the Supervisor restarts it automatically, usually within 30 seconds.

This is why HA OS installations are self-healing in a way that bare Core installs aren't. The Supervisor runs a health check loop every 60 seconds. It also controls network configuration, audio routing, and hardware access for add-ons. Without the Supervisor, you're managing all of that manually in the host OS.

Getting started with Home Assistant OS

What Does HA Core Actually Handle?

HA Core is the Python application at the center of everything. It runs as a single process with an asyncio event loop, which is worth understanding, it's single-threaded but asynchronous, handling hundreds of concurrent tasks through cooperative multitasking rather than parallel threads. In my setup with 140 entities, HA Core's CPU usage sits at about 3% on a Raspberry Pi 5 at idle.

HA Core contains several subsystems that run together.

The State Machine

The state machine is a dictionary of every entity in your system. Each entry holds the entity ID, current state value, attributes (like brightness or temperature), and timestamps for last changed and last updated. When a ZigBee sensor reports a new temperature, the ZigBee integration writes to the state machine. That write triggers a state_changed event. Everything downstream reacts to that event.

The Event Bus

The event bus is publish-subscribe at the application level. It's not a separate service, it's a Python class inside HA Core. Events are synchronous within the asyncio loop: when an event fires, all subscribers run before the next event processes. This means automation chains in HA are deterministic in order, if Automation A and Automation B both listen for the same trigger, they'll always fire in registration order, not randomly. That behavior matters when debugging complex automation conflicts.

The Automation Engine and Recorder

Automations are loaded from automations.yaml (or the database if created via UI) at startup. Each automation registers listeners against the event bus for its trigger conditions. When a trigger fires, the engine checks conditions, then dispatches actions, all within that same asyncio loop.

The Recorder is a separate thread (one of the few in HA) that writes state changes to a database. SQLite is the default, stored at /config/home-assistant_v2.db. For installs with fewer than 40-50 entities and default 10-day history, SQLite is perfectly adequate. I tested both SQLite and the MariaDB add-on on a 120-entity install, switching to MariaDB reduced history query time from 8 seconds to under 1.8 seconds and cut disk writes by about 30%, which matters on SD cards.

What Are Add-ons and How Do They Work?

Add-ons are Docker containers managed by the Supervisor, completely isolated from HA Core. Mosquitto (MQTT broker), Node-RED (visual automation editor), Grafana (metrics dashboards), ESPHome (for flashing ESP32/ESP8266 devices), and the File Editor are all add-ons. Each runs in its own container with its own network namespace.

They communicate with HA Core via the Supervisor API or directly via MQTT. They don't share memory with Core. This means a poorly-written add-on, or even one that crashes in a loop, can't corrupt HA Core's state. You can install, stop, uninstall, and update add-ons without restarting HA Core at all.

Worth noting: add-ons are only available on HA OS and Supervised installations. If you run HA Container or Core, you manage equivalent services (like Mosquitto) yourself on the host.

Adding devices via Zigbee protocol

How Does Local Processing Affect Reliability?

Every state change, every automation trigger, every entity update processes on your local hardware. No cloud call. No round-trip to a vendor server. In practice, this means lights respond in under 100ms for most ZigBee and Z-Wave commands, compared to 300-800ms for cloud-dependent devices on a good day, and "not at all" when the vendor's servers are down.

The cloud-reliability argument is real. In 2023, Tuya's cloud had two outages exceeding 4 hours each, according to their status page history. Anyone running cloud-dependent Tuya devices lost automation functionality entirely. HA users with local-only setups didn't notice.

HA vs other platforms

How Are Entities, Devices, and Areas Organized?

Devices, entities, and areas form a three-level organizational hierarchy in the HA registry. A device represents a physical piece of hardware. An entity is one controllable or measurable property of that device, one device can have a dozen entities. An area is a room or zone you define, and you assign devices to areas.

This hierarchy matters most for automations. You can trigger "turn off all lights in the living room area" without listing individual entity IDs. The Lovelace frontend (HA's dashboard system) auto-generates area cards from this registry. I use areas for every room in my house, it makes new-device setup much faster because area assignment propagates to all relevant automations automatically.

Why Does Understanding Architecture Matter for Debugging?

Knowing the layers answers most support questions immediately. Automation not triggering? Check the event bus, is the state actually changing? Use Developer Tools > Events to watch state_changed events in real time. Add-on failing to start? That's a Supervisor issue, check the Supervisor log, not the HA Core log. Slow history queries? That's the Recorder, switch to MariaDB or reduce the history retention period.

The architecture is also why HA scales from a $35 Raspberry Pi Zero 2 W (adequate for under 30 entities, slow UI) to a full Intel NUC or mini-PC handling 500+ entities without breaking a sweat. Every layer is tunable independently. The Home Assistant architecture overview in the official docs goes deeper if you want the source-level detail.

Full HA terminology reference

What You Need to Know About Installation Types

If you're new to HA, the installation type you choose determines which layers are available to you. It's worth taking a technical look at the four options before you install, because switching later means migrating your config. Here's what each option gives you:

• Home Assistant OS: Full stack. HA OS + Supervisor + Core + Add-ons. Recommended for most users. Automated updates, snapshot backups, add-on store.
• Home Assistant Supervised: You bring your own Debian Linux, but the Supervisor still runs. You get the add-on store and automated Core updates. More work to maintain, but valid on existing hardware.
• Home Assistant Container: Core running as a single Docker container. No Supervisor, no add-on store. You manage companion services yourself. Good for NAS users who already run Docker.
• Home Assistant Core: Pure Python install, no Docker at all. Maximum flexibility, minimum convenience. Niche use case for developers or constrained environments.

I've explained this distinction to a lot of beginners, and the confusion almost always comes from not knowing the Supervisor exists as a separate layer. Once that clicks, the installation types make immediate sense.

The difference between Container and OS also explains a common frustration: users install HA Container expecting to find the add-on store, and it isn't there. The add-on store is a Supervisor feature. Container doesn't have the Supervisor, so it doesn't have the store. You'd need to run Mosquitto or Node-RED as separate Docker containers yourself.

How Configuration Files Map to the Architecture

Each architectural layer has a corresponding set of files you can edit. Understanding where things live saves time when you need to make changes.

HA Core reads its main config from /config/configuration.yaml. Automations go in /config/automations.yaml or into the database if you use the visual editor. Scripts live in /config/scripts.yaml. The Recorder's database sits at /config/home-assistant_v2.db. Add-on configs are stored separately under /addon_configs/ and are managed per-add-on.

The Supervisor itself stores OS-level config outside the /config/ directory, in paths that HA OS manages. You don't typically edit those directly. The practical implication: when you restore a HA OS backup (snapshot), you're restoring the /config/ directory and add-on data. The OS layer restores separately via the Supervisor's full-restore function.

Home Assistant's architecture isn't complexity for its own sake. Each layer exists to solve a real problem: OS isolation prevents hardware quirks from breaking software, the Supervisor handles operational overhead automatically, the asyncio event loop makes Core efficient on low-power hardware, and Docker add-ons keep third-party services from touching Core. Once you see the layers, the whole system starts making sense, and troubleshooting goes from guessing to targeted.