# homebridge/docker-homebridge architecture

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

- Interactive diagram: https://gitdiagram.com/homebridge/docker-homebridge
- Repository: https://github.com/homebridge/docker-homebridge

## Overview

##### Main Components

a. Container Layer:
- Docker Container (Ubuntu 24.04 base)
- Multi-arch support (amd64, arm32v7, arm64v8)

b. Core Services (represented as individual components):
- Homebridge Core Service
- Homebridge UI (running on port 8581)
- Avahi mDNS Service
- D-Bus Service
- S6 Overlay (process supervisor)

c. Storage/Volume Components:
- Host Volume Mount (/homebridge)
- Configuration Storage
- Plugin Storage

d. Network Layer:
- Host Network Interface (--net=host)
- HomeKit Protocol Interface
- UI Web Interface

##### Component Relationships

- Docker Host → Container (containment relationship)
- Container → Host Network (direct network access)
- Homebridge Core ↔ HomeKit Devices
- Homebridge Core ↔ Configuration Storage
- Homebridge UI ↔ Web Browsers
- Avahi Service ↔ Network (mDNS broadcasting)

##### Specific Implementation Details

- Green: Running Services (Homebridge, UI, Avahi)
- Blue: Storage Components
- Yellow: Network Interfaces
- Gray: Infrastructure Components (Docker, S6)

##### Additional Elements

Annotations for:
- Port mappings (8581 for UI)
- Volume mount points
- Health check endpoint
- Timezone configuration
- FFmpeg support

##### Architectural Patterns

Highlight:
- Service supervision hierarchy (S6 Overlay)
- Container orchestration
- Plugin architecture
- Configuration management

**[Host System Layer]**
- ↓
**[Docker Container Layer]**
- ↓
**[Service Layer (S6 Managed)]**
- ↓
**[Application Layer]**
- ↓
**[Storage Layer]**

Important Implementation Notes:
- Host network mode requirement
- Multi-arch support
- Separation between persistent and ephemeral storage
- UI as the primary management interface
- Health check mechanism

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Host
        HN[Host Network]
        HV[Host Volume]
    end

    subgraph Container["Docker Container (Ubuntu 24.04)"]
        direction TB
        click Container "https://github.com/homebridge/docker-homebridge/tree/latest/Dockerfile"
        
        subgraph Arch["Multi-Architecture Support"]
            AMD["AMD64"]
            ARM32["ARM32v7"]
            ARM64["ARM64v8"]
        end

        subgraph Services["Service Layer"]
            direction TB
            S6[S6 Overlay]:::supervisor
            click S6 "https://github.com/homebridge/docker-homebridge/tree/latest/rootfs/etc/s6-overlay/"
            
            HB[Homebridge Core]:::service
            click HB "https://github.com/homebridge/docker-homebridge/tree/latest/rootfs/etc/s6-overlay/s6-rc.d/homebridge/"
            
            UI[Homebridge UI<br>Port 8581]:::service
            
            AVAHI[Avahi mDNS]:::service
            click AVAHI "https://github.com/homebridge/docker-homebridge/tree/latest/rootfs/etc/s6-overlay/s6-rc.d/avahi/"
            
            DBUS[D-Bus Service]:::service
            click DBUS "https://github.com/homebridge/docker-homebridge/tree/latest/rootfs/etc/s6-overlay/s6-rc.d/dbus/"
            
            TZ[Time Zone<br>Management]:::service
            click TZ "https://github.com/homebridge/docker-homebridge/tree/latest/rootfs/etc/s6-overlay/s6-rc.d/tzupdate/"
        end

        subgraph Storage["Storage Layer"]
            CONF[Configuration<br>Storage]:::storage
            PLUG[Plugin<br>Storage]:::storage
            NPM[NPM Config]:::storage
            click NPM "https://github.com/homebridge/docker-homebridge/blob/latest/rootfs/defaults/.npmrc"
        end

        subgraph Setup["Setup Layer"]
            STARTUP[Startup Scripts]:::setup
            click STARTUP "https://github.com/homebridge/docker-homebridge/blob/latest/rootfs/defaults/startup.sh"
            USERDATA[User Data<br>Management]:::setup
            click USERDATA "https://github.com/homebridge/docker-homebridge/tree/latest/rootfs/etc/s6-overlay/s6-rc.d/userdata/"
        end
    end

    subgraph External["External Layer"]
        WB[Web Browsers]:::external
        HK[HomeKit Devices]:::external
    end

    %% Relationships
    HN --- Container
    HV --- Storage
    S6 --> HB & UI & AVAHI & DBUS & TZ
    HB --> CONF
    HB --> PLUG
    HB --> NPM
    STARTUP --> USERDATA
    UI --> WB
    HB --> HK
    AVAHI --> HN

    %% Styles
    classDef service fill:#90EE90
    classDef storage fill:#87CEEB
    classDef external fill:#FFE4B5
    classDef supervisor fill:#A9A9A9
    classDef setup fill:#DDA0DD

    %% Legend
    subgraph Legend
        L1[Running Services]:::service
        L2[Storage Components]:::storage
        L3[External Systems]:::external
        L4[Supervisors]:::supervisor
        L5[Setup Components]:::setup
    end
```
