# home-assistant/operating-system architecture

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

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

## Overview

##### Hardware Layer
- Supported hardware platforms (Raspberry Pi, ODROID, x86-64, etc.)
- Bootloader separation (UEFI/GRUB for x86-64, U-Boot for ARM devices)

##### Operating System Layer
- Buildroot-based Linux core
- File System Structure:
- SquashFS (read-only root)
- ZRAM for temporary storage (/tmp, /var)
- Overlay file system for persistence
- Kernel features (AppArmor, ZRAM)

##### Container Platform
- Docker Engine as the primary container runtime
- Containerd for container management
- Container networking bridge

##### Application Layer
- Home Assistant Supervisor (primary container)
- Home Assistant Core (managed by Supervisor)
- -ons (containerized applications)

##### Update/Security System
- RAUC update system
- A/B partition scheme for updates
- AppArmor security module

##### Layer Organization (bottom to top)
- [Hardware Layer]
- ↑
- [Bootloader Layer (UEFI/U-Boot)]
- ↑
- [Operating System Layer]
- ↑
- [Container Platform]
- ↑
- [Application Layer]

##### Connection Types
- Double lines: Data flow

##### Important Details
- File system mount points
- Network interfaces
- Update paths
- Security boundaries

##### A/B partition scheme for updates
- [Boot] → [System A] ↔ [RAUC] ↔ [System B]

##### Overlay system
- [Read-only Root] → [Overlay] → [Runtime FS]

##### Container isolation
- [Docker Engine]
- [Supervisor Container]
- [Home Assistant Container]
- [Add-on Containers]

##### Document mount points
- /mnt/boot
- /mnt/data
- /mnt/overlay
- Various bind mounts

Remember to include version compatibility information and system requirements in supplementary documentation.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and Classes
    classDef hardware fill:#b3d9ff,stroke:#333
    classDef os fill:#90EE90,stroke:#333
    classDef container fill:#FFB366,stroke:#333
    classDef app fill:#DDA0DD,stroke:#333
    classDef security fill:#FF9999,stroke:#333
    classDef filesystem fill:#E6E6E6,stroke:#333

    %% Hardware Layer
    subgraph Hardware
        RPI["Raspberry Pi"]:::hardware
        ODROID["ODROID"]:::hardware
        X86["x86-64"]:::hardware
    end

    %% Bootloader Layer
    subgraph Bootloader
        UEFI["UEFI/GRUB"]:::hardware
        UBOOT["U-Boot"]:::hardware
    end

    %% Operating System Layer
    subgraph OS
        Linux["Buildroot Linux Core"]:::os
        Kernel["Linux Kernel"]:::os
        FS["File System"]:::filesystem
    end

    %% File System Components
    subgraph FileSystem
        SquashFS["SquashFS (Read-only)"]:::filesystem
        ZRAM["ZRAM Storage"]:::filesystem
        Overlay["Overlay FS"]:::filesystem
        MountPoints["Mount Points"]:::filesystem
    end

    %% Container Platform
    subgraph Containers
        Docker["Docker Engine"]:::container
        Containerd["Containerd"]:::container
        Network["Container Network Bridge"]:::container
    end

    %% Application Layer
    subgraph Applications
        Supervisor["Home Assistant Supervisor"]:::app
        Core["Home Assistant Core"]:::app
        Addons["Add-ons"]:::app
    end

    %% Security & Updates
    subgraph Security
        AppArmor["AppArmor"]:::security
        RAUC["RAUC Update System"]:::security
        ABSystem["A/B Partition Scheme"]:::security
    end

    %% Relationships
    RPI & ODROID & X86 --> UBOOT
    X86 --> UEFI
    UEFI & UBOOT --> Linux
    Linux --> Kernel
    Kernel --> FS
    FS --> SquashFS & ZRAM & Overlay
    SquashFS & ZRAM & Overlay --> MountPoints
    Linux --> Docker
    Docker --> Containerd
    Containerd --> Network
    Docker --> Supervisor
    Supervisor --> Core
    Supervisor --> Addons
    Linux --> AppArmor
    AppArmor --> Supervisor
    Linux --> RAUC
    RAUC --> ABSystem

    %% Click Events
    click RPI "https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/board/raspberrypi/"
    click ODROID "https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/board/hardkernel/"
    click X86 "https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/board/pc/"
    click UBOOT "https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/bootloader/"
    click Linux "https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/rootfs-overlay/"
    click Kernel "https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/kernel/"
    click Docker "https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/rootfs-overlay/etc/docker/"
    click Containerd "https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/rootfs-overlay/etc/containerd/"
    click Supervisor "https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/package/hassio/"
    click RAUC "https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/ota/"
    click AppArmor "https://github.com/home-assistant/operating-system/blob/dev/buildroot-external/rootfs-overlay/usr/lib/systemd/system/hassos-apparmor.service"
    click MountPoints "https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/rootfs-overlay/mnt/"
    click Network "https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/rootfs-overlay/etc/NetworkManager/"
```
