Home Assistant Architecture Explained, Every Layer You Need to Know

This post may contain affiliate links. As an Amazon Associate we earn from qualifying purchases. Disclosure.

Most people treat Home Assistant as a black box. You press a button, a light turns on, and nobody asks how. That works until 2 AM, when an automation doesn't fire and you have no idea which part of the system to open first. Knowing the layers tells you where to look.

I run Home Assistant OS on a bare Raspberry Pi 5 mounted on a DIN rail in the house's electrical cabinet, with a Home Assistant Connect ZBT-1 as the Zigbee coordinator. I haven't profiled it down to CPU percentages, so you won't find invented benchmarks below. What follows is how the system is built, checked against the official documentation.

TL;DR: Home Assistant is a stack. HA OS is the host system, the Supervisor manages containers on top of it, Core runs the state machine, event bus and automations, and apps (called add-ons until 2026) run as separate containers. Everything happens on your own hardware.

What Does the Layered Architecture Look Like?

Four layers, each with one job. Home Assistant OS is the host operating system, a minimal Linux built only to run Home Assistant. The Supervisor sits on top and manages the containers. Core is the Python application that holds all the smart home logic. Apps are separate containers for auxiliary services such as an MQTT broker.

Why split it up? Because a failure in one layer shouldn't take down the others. A misbehaving app can't corrupt Core's state, and a Core update doesn't touch the operating system. It's the same separation of concerns you'd want in any production system, applied to a house.

What Does the Supervisor Do?

The Supervisor is the layer most people never think about. It installs and updates the operating system, Core and apps. It creates and restores backups. It watches the other pieces and restarts what falls over. It also decides which hardware an app is allowed to touch, such as a USB Zigbee stick.

That's why a HA OS install feels self-maintaining in a way a bare Core install doesn't. Without the Supervisor, all of that is your job, on a host system you also have to keep patched.

What Does Core Actually Handle?

Core is the Python application at the center. It runs on an asyncio event loop, which means it's single-threaded but asynchronous: many tasks make progress by taking turns instead of running in parallel threads. That design suits a hub that mostly waits for devices to speak.

Three pieces inside Core matter for debugging.

The State Machine

The state machine is the live picture of your home. Every entity has an ID, a current state, attributes such as brightness or temperature, and timestamps for the last change. When a Zigbee sensor reports a new reading, its integration updates the entity, and that update becomes an event.

The Event Bus

The event bus is publish-subscribe inside Core. Something happens, an event with a type and data is fired, and every subscriber to that type reacts. A state change travels as a state_changed event carrying the old and new state. Components never reference each other directly, which is why a custom integration can hook into core behavior without editing core code.

You can watch it live. In Developer Tools, the Events tab lets you listen to state_changed and see exactly what your devices are reporting. If an automation isn't firing, this is the first place to look, because it answers the real question: did the state actually change?

Automations and the Recorder

An automation registers its triggers with the event bus. When a trigger matches, Core checks the conditions and runs the actions. The Recorder is the part that writes states and events to a database so you have history. It uses SQLite by default, stored as home-assistant_v2.db in the configuration directory, and keeps 10 days of history unless you change it.

Is SQLite enough? For most homes, yes. If history panels get slow, reduce the retention period and exclude noisy entities before you touch the database engine. Only then consider MariaDB or PostgreSQL, which the recorder supports. I'd call jumping straight to an external database the most common over-engineering mistake in Home Assistant.

What Are Apps (Formerly Add-ons)?

Apps are containers managed by the Supervisor, kept apart from Core. Mosquitto (an MQTT broker), Node-RED, ESPHome and the file editor are typical examples. Home Assistant renamed add-ons to apps in release 2026.2 to stop newcomers confusing them with integrations (the rename announcement). The function didn't change, so older guides that say add-on describe the same thing.

The practical benefit is isolation. You can install, stop and update an app without restarting Core, and a crashing app doesn't corrupt Core's state. Apps exist only where the Supervisor exists: HA OS and Supervised installs. On Container or Core you run Mosquitto and friends yourself.

How Do Devices, Entities and Areas Fit Together?

Three levels. A device is a physical thing. An entity is one measurable or controllable property of it, and one device often has several. An area is a room or zone you define, and you assign devices to it.

Areas pay off in automations. "Turn off every light in the hallway" doesn't need a list of entity IDs, and a new bulb you add to the area is picked up automatically. Set the areas up on day one, because retrofitting them across dozens of devices is tedious.

Why Does Local Processing Matter?

State changes, triggers and actions are processed on your own hardware. No round trip to a vendor server is involved for a local integration such as Zigbee. When the internet drops, automations built on local devices keep running, and only remote access and cloud-based integrations stop.

That's the reason I picked it for the house. In the flat, cloud automations on SmartThings went quiet during ISP outages: no error, no alarm, just a dark room. Local logic doesn't fail that way. Another local hub handles the same problem differently, as the Homey comparison linked below shows.

Which Installation Type Should You Choose?

The type decides which layers you get, and switching later means migrating:

• Home Assistant OS: the full stack, with Supervisor, apps and backups. The right default.
• Home Assistant Supervised: the Supervisor on a Debian system you maintain yourself. More work for the same result.
• Home Assistant Container: Core in a single Docker container, no Supervisor, no app store.
• Home Assistant Core: the Python application alone, for developers and constrained setups.

My opinion: unless you already run a NAS full of containers and want Home Assistant to join them, skip Container. People install it, look for the app store, and discover it was never there. The store belongs to the Supervisor.

Where Do the Files Live?

Core reads its main settings from configuration.yaml in the configuration directory, with automations in automations.yaml unless you use the visual editor, which stores them there as well. The recorder database sits in the same directory. Backups taken through the Supervisor cover your configuration and app data, which is why a restore on fresh hardware brings the system back.

So What Should You Remember?

Each layer exists to solve one problem. The operating system keeps hardware quirks away from the software, the Supervisor handles maintenance, Core keeps the logic fast and local, and apps keep third-party services out of Core. Once you see that, troubleshooting becomes targeted: an app won't start, look at the Supervisor; an automation won't fire, watch the events; history is slow, look at the recorder.

Architecture explained, the next step is practice. Put the layers to work with the setup guide and the Zigbee hub roundup linked below.