# home-assistant/supervisor architecture

> Architecture diagram of the GitHub repository home-assistant/supervisor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/home-assistant/supervisor
- Repository: https://github.com/home-assistant/supervisor

## Overview

Home Assistant Supervisor is the control plane for a container-based Home Assistant installation. Home Assistant or an administrator uses its API to manage applications and installation settings; the Supervisor coordinates those operations across Docker, host services, backups, and system integrations. The graph preserves the README’s central API-to-management workflow and the major product subsystems visible in the tree. Some relationships are documented rather than demonstrated in excerpts, so those edges cite the README or are marked unverified; unsampled modules are represented only at supported directory paths.

Main entry points: [`supervisor/coresys.py`](https://github.com/home-assistant/supervisor/blob/main/supervisor/coresys.py) (Core orchestration), [`supervisor/api`](https://github.com/home-assistant/supervisor/tree/main/supervisor/api) (Supervisor API), [`supervisor/host/manager.py`](https://github.com/home-assistant/supervisor/blob/main/supervisor/host/manager.py) (Host management), [`supervisor/apps/manager.py`](https://github.com/home-assistant/supervisor/blob/main/supervisor/apps/manager.py) (Application manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_api["Supervisor API"]
  node_core["Core orchestration<br/>[coresys.py]"]
  node_jobs["Job coordination<br/>[decorator.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_resolution["Issue resolution"]
end

subgraph group_apps["Applications"]
  node_app_manager["Application manager<br/>[manager.py]"]
  node_app["Application lifecycle<br/>[app.py]"]
  node_store["Application store<br/>[repository.py]"]
  node_docker["Container management<br/>[manager.py]"]
end

subgraph group_system["Host and system"]
  node_host["Host management<br/>[manager.py]"]
  node_network["Network settings<br/>[network.py]"]
  node_hardware["Hardware management<br/>[manager.py]"]
  node_os["OS management<br/>[manager.py]"]
end

subgraph group_data["Data management"]
  node_backups["Backup management<br/>[manager.py]"]
  node_mounts["Mount management<br/>[manager.py]"]
end

subgraph group_integrations["Integrations"]
  node_homeassistant["Home Assistant Core<br/>[core.py]"]
  node_dbus["D-Bus integration<br/>[manager.py]"]
  node_plugins["System plugins<br/>[manager.py]"]
  node_services["Service management<br/>[interface.py]"]
  node_discovery["Network discovery"]
end

node_ha(("Home Assistant"))
node_operator(("Administrator"))

node_ha -->|"controls through"| node_api
node_operator -.->|"manages through"| node_api
node_api -.->|"validates access"| node_auth
node_api -->|"manages apps"| node_app_manager
node_app_manager -->|"manages lifecycle"| node_app
node_app_manager -->|"uses app data"| node_store
node_app -.->|"controls containers"| node_docker
node_api -->|"changes settings"| node_network
node_core -->|"initializes"| node_api
node_core -->|"initializes"| node_app_manager
node_core -->|"initializes"| node_backups
node_core -->|"initializes"| node_docker
node_core -->|"initializes"| node_host
node_core -->|"initializes"| node_hardware
node_core -->|"initializes"| node_os
node_core -->|"initializes"| node_dbus
node_core -->|"initializes"| node_homeassistant
node_core -->|"initializes"| node_plugins
node_core -->|"initializes"| node_discovery
node_core -->|"initializes"| node_resolution
node_core -.->|"provides tasks"| node_jobs
node_backups -->|"backs up apps"| node_app
node_host -->|"manages network"| node_network
node_host -->|"manages services"| node_services
node_host -->|"manages hardware"| node_hardware
node_host -.->|"uses D-Bus"| node_dbus
node_os -->|"uses RAUC"| node_dbus
node_plugins -.->|"provides services"| node_services
node_api -.->|"manages backups"| node_backups
node_api -.->|"manages host"| node_host
node_api -.->|"manages OS"| node_os
node_api -.->|"manages mounts"| node_mounts

click node_api "https://github.com/home-assistant/supervisor/tree/main/supervisor/api"
click node_core "https://github.com/home-assistant/supervisor/blob/main/supervisor/coresys.py"
click node_jobs "https://github.com/home-assistant/supervisor/blob/main/supervisor/jobs/decorator.py"
click node_auth "https://github.com/home-assistant/supervisor/blob/main/supervisor/auth.py"
click node_app_manager "https://github.com/home-assistant/supervisor/blob/main/supervisor/apps/manager.py"
click node_app "https://github.com/home-assistant/supervisor/blob/main/supervisor/apps/app.py"
click node_store "https://github.com/home-assistant/supervisor/blob/main/supervisor/store/repository.py"
click node_docker "https://github.com/home-assistant/supervisor/blob/main/supervisor/docker/manager.py"
click node_homeassistant "https://github.com/home-assistant/supervisor/blob/main/supervisor/homeassistant/core.py"
click node_backups "https://github.com/home-assistant/supervisor/blob/main/supervisor/backups/manager.py"
click node_mounts "https://github.com/home-assistant/supervisor/blob/main/supervisor/mounts/manager.py"
click node_host "https://github.com/home-assistant/supervisor/blob/main/supervisor/host/manager.py"
click node_network "https://github.com/home-assistant/supervisor/blob/main/supervisor/host/network.py"
click node_hardware "https://github.com/home-assistant/supervisor/blob/main/supervisor/hardware/manager.py"
click node_os "https://github.com/home-assistant/supervisor/blob/main/supervisor/os/manager.py"
click node_dbus "https://github.com/home-assistant/supervisor/blob/main/supervisor/dbus/manager.py"
click node_plugins "https://github.com/home-assistant/supervisor/blob/main/supervisor/plugins/manager.py"
click node_services "https://github.com/home-assistant/supervisor/blob/main/supervisor/services/interface.py"
click node_discovery "https://github.com/home-assistant/supervisor/tree/main/supervisor/discovery"
click node_resolution "https://github.com/home-assistant/supervisor/tree/main/supervisor/resolution"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_core,node_jobs,node_auth,node_resolution toneBlue
class node_app_manager,node_app,node_store,node_docker toneAmber
class node_host,node_network,node_hardware,node_os toneMint
class node_backups,node_mounts toneRose
class node_homeassistant,node_dbus,node_plugins,node_services,node_discovery,node_ha,node_operator toneIndigo
```

## Components

### Control plane

- [Supervisor API](https://github.com/home-assistant/supervisor/tree/main/supervisor/api): `supervisor/api`
- [Core orchestration](https://github.com/home-assistant/supervisor/blob/main/supervisor/coresys.py): `supervisor/coresys.py`
- [Job coordination](https://github.com/home-assistant/supervisor/blob/main/supervisor/jobs/decorator.py): `supervisor/jobs/decorator.py`
- [Authentication](https://github.com/home-assistant/supervisor/blob/main/supervisor/auth.py): `supervisor/auth.py`
- [Issue resolution](https://github.com/home-assistant/supervisor/tree/main/supervisor/resolution): `supervisor/resolution`

### Applications

- [Application manager](https://github.com/home-assistant/supervisor/blob/main/supervisor/apps/manager.py): `supervisor/apps/manager.py`
- [Application lifecycle](https://github.com/home-assistant/supervisor/blob/main/supervisor/apps/app.py): `supervisor/apps/app.py`
- [Application store](https://github.com/home-assistant/supervisor/blob/main/supervisor/store/repository.py): `supervisor/store/repository.py`
- [Container management](https://github.com/home-assistant/supervisor/blob/main/supervisor/docker/manager.py): `supervisor/docker/manager.py`

### Host and system

- [Host management](https://github.com/home-assistant/supervisor/blob/main/supervisor/host/manager.py): `supervisor/host/manager.py`
- [Network settings](https://github.com/home-assistant/supervisor/blob/main/supervisor/host/network.py): `supervisor/host/network.py`
- [Hardware management](https://github.com/home-assistant/supervisor/blob/main/supervisor/hardware/manager.py): `supervisor/hardware/manager.py`
- [OS management](https://github.com/home-assistant/supervisor/blob/main/supervisor/os/manager.py): `supervisor/os/manager.py`

### Data management

- [Backup management](https://github.com/home-assistant/supervisor/blob/main/supervisor/backups/manager.py): `supervisor/backups/manager.py`
- [Mount management](https://github.com/home-assistant/supervisor/blob/main/supervisor/mounts/manager.py): `supervisor/mounts/manager.py`

### Integrations

- [Home Assistant Core](https://github.com/home-assistant/supervisor/blob/main/supervisor/homeassistant/core.py): `supervisor/homeassistant/core.py`
- [D-Bus integration](https://github.com/home-assistant/supervisor/blob/main/supervisor/dbus/manager.py): `supervisor/dbus/manager.py`
- [System plugins](https://github.com/home-assistant/supervisor/blob/main/supervisor/plugins/manager.py): `supervisor/plugins/manager.py`
- [Service management](https://github.com/home-assistant/supervisor/blob/main/supervisor/services/interface.py): `supervisor/services/interface.py`
- [Network discovery](https://github.com/home-assistant/supervisor/tree/main/supervisor/discovery): `supervisor/discovery`

### Other components

- **Home Assistant**
- **Administrator**

## Connections

- Home Assistant → Supervisor API: controls through
- Administrator → Supervisor API: manages through
- Supervisor API → Authentication: validates access
- Supervisor API → Application manager: manages apps (evidence: `supervisor/api/apps.py`)
- Application manager → Application lifecycle: manages lifecycle (evidence: `supervisor/apps/manager.py`)
- Application manager → Application store: uses app data (evidence: `supervisor/apps/manager.py`)
- Application lifecycle → Container management: controls containers (evidence: `supervisor/apps/app.py`)
- Supervisor API → Network settings: changes settings
- Core orchestration → Supervisor API: initializes (evidence: `supervisor/coresys.py`)
- Core orchestration → Application manager: initializes (evidence: `supervisor/coresys.py`)
- Core orchestration → Backup management: initializes (evidence: `supervisor/coresys.py`)
- Core orchestration → Container management: initializes (evidence: `supervisor/coresys.py`)
- Core orchestration → Host management: initializes (evidence: `supervisor/coresys.py`)
- Core orchestration → Hardware management: initializes (evidence: `supervisor/coresys.py`)
- Core orchestration → OS management: initializes (evidence: `supervisor/coresys.py`)
- Core orchestration → D-Bus integration: initializes (evidence: `supervisor/coresys.py`)
- Core orchestration → Home Assistant Core: initializes (evidence: `supervisor/coresys.py`)
- Core orchestration → System plugins: initializes (evidence: `supervisor/coresys.py`)
- Core orchestration → Network discovery: initializes (evidence: `supervisor/coresys.py`)
- Core orchestration → Issue resolution: initializes (evidence: `supervisor/coresys.py`)
- Core orchestration → Job coordination: provides tasks (evidence: `supervisor/jobs/decorator.py`)
- Backup management → Application lifecycle: backs up apps (evidence: `supervisor/backups/manager.py`)
- Host management → Network settings: manages network (evidence: `supervisor/host/manager.py`)
- Host management → Service management: manages services (evidence: `supervisor/host/manager.py`)
- Host management → Hardware management: manages hardware (evidence: `supervisor/host/manager.py`)
- Host management → D-Bus integration: uses D-Bus
- OS management → D-Bus integration: uses RAUC (evidence: `supervisor/os/manager.py`)
- System plugins → Service management: provides services
- Supervisor API → Backup management: manages backups
- Supervisor API → Host management: manages host
- Supervisor API → OS management: manages OS
- Supervisor API → Mount management: manages mounts
