Architecture
How everything fits together, and the decisions behind it.
Home Assistant runs millions of homes, on anything from a small Raspberry Pi to a server in a closet. Under the hood, it is a set of pieces that work together, built by thousands of people over more than a decade. This area explains how.
You don't need to understand all of it to contribute. Start with the big picture, and go deeper when your work takes you there. Every page starts with the short version, and goes into detail after, for those who want it.
- The big picture: every piece on one page, and how they connect.
- Principles: the ideas behind how Home Assistant is built.
- How architecture decisions are made: where architecture is discussed, and how to take part.
- Repositories: where the code lives.
- Inside Home Assistant Core: from startup to entities, the Python application at the center.
- How the pieces talk: the APIs, and logging in.
- The frontend: the web interface, and how dashboards work.
- Around Core: the Supervisor, Home Assistant OS, apps, the companion apps, the cloud, and voice.
- How Home Assistant handles trust, in the Security area: who Home Assistant trusts, and where it can be attacked.
This area explains how things work. The work itself happens in the other areas of this site. Each one starts with a small first contribution:
| You want to work on | Go to | First step |
|---|---|---|
| Home Assistant Core and integrations | Core and integrations | Your first contribution to Core |
| The web interface and dashboards | Frontend | Your first frontend contribution |
| How the interface looks, works, and reads | Design | Your first design contribution |
| The Android and Apple apps | Companion apps | Your first companion app contribution |
| The Supervisor and Home Assistant OS | OS and Supervisor | Your first contribution to the Supervisor |
| Software that runs next to Home Assistant | Apps | Your first app |
| The sentences Assist understands | Voice translations | Contribute sentences and responses |
| Home Assistant in your language | Translations | Your first translation |
| The user documentation | Writing docs | Your first docs fix |
| Keeping homes safe | Security | Your first security contribution |
| Testing and shipping releases | Releases | Your first beta test |
Not sure yet? Your first contribution in Get started helps you pick.
Everyone who wants to know how Home Assistant works under the hood. The pages assume you know Home Assistant as a user. Where code comes in, it is Python for Core and TypeScript for the frontend, but the explanation around it doesn't need you to read it.
The code is the source of truth. Pages point to where the code they describe lives, so you can check, and read further. Every page ends with Work on this: where to go when you want to change what it describes.
- Architecture discussions happen in the architecture repository.
- Questions while you work go to the #developers channel on Discord. Can't see it? Under Channels & Roles, choose I want to contribute dev skills to Home Assistant.
- Found something on these pages that is wrong or outdated? Use the edit link at the bottom of the page.