# akentner/homeassistant-addons architecture

> Architecture diagram of the GitHub repository akentner/homeassistant-addons, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akentner/homeassistant-addons
- Repository: https://github.com/akentner/homeassistant-addons

## Overview

This is a Home Assistant add-on monorepo: its add-ons provide user-facing services rather than one shared application. The graph preserves the README’s documented product capabilities and shows the principal paths from add-on users or operators to results. The admin UI and HAOS Monitor include sampled runtime wiring; most other add-ons are represented at their documented subsystem level because their implementation was not sampled. Edges use README evidence where applicable, so implementation details of those add-ons remain unspecified.

Main entry points: [`haos-monitor/app/main.py`](https://github.com/akentner/homeassistant-addons/blob/main/haos-monitor/app/main.py) (Host monitor), [`haos-monitor/app/web/server.py`](https://github.com/akentner/homeassistant-addons/blob/main/haos-monitor/app/web/server.py) (Monitor web API), [`iac-runner/internal/jobq/queue.go`](https://github.com/akentner/homeassistant-addons/blob/main/iac-runner/internal/jobq/queue.go) (Run execution), [`admin-ui/app/web/skeleton/server.py`](https://github.com/akentner/homeassistant-addons/blob/main/admin-ui/app/web/skeleton/server.py) (Ingress web server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_admin["Admin interfaces"]
  node_admin_app["Admin UI app<br/>[main.py]"]
  node_admin_server["Ingress web server<br/>[server.py]"]
  node_admin_router["Request router<br/>[router.py]"]
  node_admin_static["Static asset serving<br/>[static.py]"]
  node_admin_frontend["Admin frontend<br/>[app.mjs]"]
end

subgraph group_monitor["Monitoring and diagnostics"]
  node_haos_monitor["Host monitor<br/>[main.py]"]
  node_haos_web["Monitor web API<br/>[server.py]"]
  node_haos_hosts["Host configuration<br/>[hosts.py]"]
  node_haos_status["Host status<br/>[status.py]"]
  node_haos_incidents["Incident history<br/>[incidents.py]"]
  node_haos_ui["Monitor dashboard<br/>[app.mjs]"]
  node_gatus["Gatus monitoring"]
end

subgraph group_services["Home services"]
  node_markdown["Markdown renderer"]
  node_phone["Phone logger"]
  node_network["Network tools"]
  node_cups["CUPS print server"]
  node_litellm["LiteLLM gateway<br/>[run_litellm.py]"]
  node_secrets["Secrets sync"]
  node_postgres[("Bundled PostgreSQL")]
end

subgraph group_infra["Infrastructure automation"]
  node_iac_operator(("IaC operator"))
  node_iac_api["IaC HTTP API<br/>[plan.go]"]
  node_iac_git["Repository checkout<br/>[manager.go]"]
  node_iac_queue["Run execution<br/>[queue.go]"]
  node_iac_state["State backends"]
  node_iac_runs[("Run records<br/>[store.go]")]
end

node_ha_user(("Home Assistant user"))
node_git_remote["Git repository"]
node_tofu["OpenTofu / Terraform"]
node_state_store[("R2, S3, or local state")]
node_ha_rest["Home Assistant REST sensor"]
node_llm_clients(("LLM clients"))

node_ha_user -->|"opens UI"| node_admin_app
node_admin_app -->|"starts server"| node_admin_server
node_admin_server -->|"dispatches requests"| node_admin_router
node_admin_server -->|"serves assets"| node_admin_static
node_admin_frontend -->|"calls API"| node_admin_server
node_ha_user -.->|"views host health"| node_haos_monitor
node_haos_monitor -->|"starts server"| node_haos_web
node_haos_web -->|"loads hosts"| node_haos_hosts
node_haos_web -->|"reads status"| node_haos_status
node_haos_web -->|"reads incidents"| node_haos_incidents
node_haos_ui -.->|"fetches overview"| node_haos_web
node_haos_monitor -.->|"records host state"| node_haos_status
node_haos_monitor -.->|"logs incidents"| node_haos_incidents
node_markdown -.->|"serves Docsify pages"| node_ha_user
node_phone -.->|"integrates with HA"| node_ha_user
node_network -->|"exposes scan results"| node_ha_rest
node_cups -.->|"shares printers"| node_ha_user
node_llm_clients -->|"sends API requests"| node_litellm
node_litellm -->|"stores keys and logs"| node_postgres
node_secrets -.->|"writes synced secrets"| node_ha_user
node_iac_operator -->|"triggers plans"| node_iac_api
node_iac_api -->|"clones repository"| node_iac_git
node_iac_git -->|"fetches source"| node_git_remote
node_iac_api -->|"queues run"| node_iac_queue
node_iac_queue -->|"runs plan or apply"| node_tofu
node_iac_queue -->|"uses backend"| node_iac_state
node_iac_state -->|"persists state"| node_state_store
node_iac_queue -.->|"records run"| node_iac_runs
node_gatus -->|"monitors status"| node_haos_monitor

click node_admin_app "https://github.com/akentner/homeassistant-addons/blob/main/admin-ui/app/main.py"
click node_admin_server "https://github.com/akentner/homeassistant-addons/blob/main/admin-ui/app/web/skeleton/server.py"
click node_admin_router "https://github.com/akentner/homeassistant-addons/blob/main/admin-ui/app/web/skeleton/router.py"
click node_admin_static "https://github.com/akentner/homeassistant-addons/blob/main/admin-ui/app/web/skeleton/static.py"
click node_admin_frontend "https://github.com/akentner/homeassistant-addons/blob/main/admin-ui/app/web/static/app.mjs"
click node_haos_monitor "https://github.com/akentner/homeassistant-addons/blob/main/haos-monitor/app/main.py"
click node_haos_web "https://github.com/akentner/homeassistant-addons/blob/main/haos-monitor/app/web/server.py"
click node_haos_hosts "https://github.com/akentner/homeassistant-addons/blob/main/haos-monitor/app/hosts.py"
click node_haos_status "https://github.com/akentner/homeassistant-addons/blob/main/haos-monitor/app/status.py"
click node_haos_incidents "https://github.com/akentner/homeassistant-addons/blob/main/haos-monitor/app/incidents.py"
click node_haos_ui "https://github.com/akentner/homeassistant-addons/blob/main/haos-monitor/app/web/static/app.mjs"
click node_markdown "https://github.com/akentner/homeassistant-addons/tree/main/markdown-renderer"
click node_phone "https://github.com/akentner/homeassistant-addons/tree/main/phone-logger"
click node_network "https://github.com/akentner/homeassistant-addons/tree/main/network-tools"
click node_cups "https://github.com/akentner/homeassistant-addons/tree/main/cups"
click node_litellm "https://github.com/akentner/homeassistant-addons/blob/main/litellm/run_litellm.py"
click node_gatus "https://github.com/akentner/homeassistant-addons/tree/main/gatus"
click node_secrets "https://github.com/akentner/homeassistant-addons/tree/main/secrets-sync"
click node_iac_api "https://github.com/akentner/homeassistant-addons/blob/main/iac-runner/internal/httpapi/handlers/plan.go"
click node_iac_git "https://github.com/akentner/homeassistant-addons/blob/main/iac-runner/internal/git/manager.go"
click node_iac_queue "https://github.com/akentner/homeassistant-addons/blob/main/iac-runner/internal/jobq/queue.go"
click node_iac_state "https://github.com/akentner/homeassistant-addons/tree/main/iac-runner/internal/statebackend"
click node_iac_runs "https://github.com/akentner/homeassistant-addons/blob/main/iac-runner/internal/runs/store.go"
click node_postgres "https://github.com/akentner/homeassistant-addons/tree/main/litellm"

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_admin_app,node_admin_server,node_admin_router,node_admin_static,node_admin_frontend,node_ha_user,node_llm_clients toneBlue
class node_haos_monitor,node_haos_web,node_haos_hosts,node_haos_status,node_haos_incidents,node_haos_ui,node_gatus,node_state_store toneAmber
class node_markdown,node_phone,node_network,node_cups,node_litellm,node_secrets,node_postgres toneMint
class node_iac_operator,node_iac_api,node_iac_git,node_iac_queue,node_iac_state,node_iac_runs toneRose
class node_git_remote,node_tofu,node_ha_rest toneIndigo
```

## Components

### Admin interfaces

- [Admin UI app](https://github.com/akentner/homeassistant-addons/blob/main/admin-ui/app/main.py): `admin-ui/app/main.py`
- [Ingress web server](https://github.com/akentner/homeassistant-addons/blob/main/admin-ui/app/web/skeleton/server.py): `admin-ui/app/web/skeleton/server.py`
- [Request router](https://github.com/akentner/homeassistant-addons/blob/main/admin-ui/app/web/skeleton/router.py): `admin-ui/app/web/skeleton/router.py`
- [Static asset serving](https://github.com/akentner/homeassistant-addons/blob/main/admin-ui/app/web/skeleton/static.py): `admin-ui/app/web/skeleton/static.py`
- [Admin frontend](https://github.com/akentner/homeassistant-addons/blob/main/admin-ui/app/web/static/app.mjs): `admin-ui/app/web/static/app.mjs`

### Monitoring and diagnostics

- [Host monitor](https://github.com/akentner/homeassistant-addons/blob/main/haos-monitor/app/main.py): `haos-monitor/app/main.py`
- [Monitor web API](https://github.com/akentner/homeassistant-addons/blob/main/haos-monitor/app/web/server.py): `haos-monitor/app/web/server.py`
- [Host configuration](https://github.com/akentner/homeassistant-addons/blob/main/haos-monitor/app/hosts.py): `haos-monitor/app/hosts.py`
- [Host status](https://github.com/akentner/homeassistant-addons/blob/main/haos-monitor/app/status.py): `haos-monitor/app/status.py`
- [Incident history](https://github.com/akentner/homeassistant-addons/blob/main/haos-monitor/app/incidents.py): `haos-monitor/app/incidents.py`
- [Monitor dashboard](https://github.com/akentner/homeassistant-addons/blob/main/haos-monitor/app/web/static/app.mjs): `haos-monitor/app/web/static/app.mjs`
- [Gatus monitoring](https://github.com/akentner/homeassistant-addons/tree/main/gatus): `gatus`

### Home services

- [Markdown renderer](https://github.com/akentner/homeassistant-addons/tree/main/markdown-renderer): `markdown-renderer`
- [Phone logger](https://github.com/akentner/homeassistant-addons/tree/main/phone-logger): `phone-logger`
- [Network tools](https://github.com/akentner/homeassistant-addons/tree/main/network-tools): `network-tools`
- [CUPS print server](https://github.com/akentner/homeassistant-addons/tree/main/cups): `cups`
- [LiteLLM gateway](https://github.com/akentner/homeassistant-addons/blob/main/litellm/run_litellm.py): `litellm/run_litellm.py`
- [Secrets sync](https://github.com/akentner/homeassistant-addons/tree/main/secrets-sync): `secrets-sync`
- [Bundled PostgreSQL](https://github.com/akentner/homeassistant-addons/tree/main/litellm): `litellm`

### Infrastructure automation

- **IaC operator**
- [IaC HTTP API](https://github.com/akentner/homeassistant-addons/blob/main/iac-runner/internal/httpapi/handlers/plan.go): `iac-runner/internal/httpapi/handlers/plan.go`
- [Repository checkout](https://github.com/akentner/homeassistant-addons/blob/main/iac-runner/internal/git/manager.go): `iac-runner/internal/git/manager.go`
- [Run execution](https://github.com/akentner/homeassistant-addons/blob/main/iac-runner/internal/jobq/queue.go): `iac-runner/internal/jobq/queue.go`
- [State backends](https://github.com/akentner/homeassistant-addons/tree/main/iac-runner/internal/statebackend): `iac-runner/internal/statebackend`
- [Run records](https://github.com/akentner/homeassistant-addons/blob/main/iac-runner/internal/runs/store.go): `iac-runner/internal/runs/store.go`

### Other components

- **Home Assistant user**
- **Git repository**
- **OpenTofu / Terraform**
- **R2, S3, or local state**
- **Home Assistant REST sensor**
- **LLM clients**

## Connections

- Home Assistant user → Admin UI app: opens UI (evidence: `admin-ui/app/main.py`)
- Admin UI app → Ingress web server: starts server (evidence: `admin-ui/app/main.py`)
- Ingress web server → Request router: dispatches requests (evidence: `admin-ui/app/web/skeleton/server.py`)
- Ingress web server → Static asset serving: serves assets (evidence: `admin-ui/app/web/skeleton/server.py`)
- Admin frontend → Ingress web server: calls API (evidence: `admin-ui/app/web/static/app.mjs`)
- Home Assistant user → Host monitor: views host health
- Host monitor → Monitor web API: starts server (evidence: `haos-monitor/app/main.py`)
- Monitor web API → Host configuration: loads hosts (evidence: `haos-monitor/app/web/server.py`)
- Monitor web API → Host status: reads status (evidence: `haos-monitor/app/web/server.py`)
- Monitor web API → Incident history: reads incidents (evidence: `haos-monitor/app/web/server.py`)
- Monitor dashboard → Monitor web API: fetches overview
- Host monitor → Host status: records host state
- Host monitor → Incident history: logs incidents
- Markdown renderer → Home Assistant user: serves Docsify pages
- Phone logger → Home Assistant user: integrates with HA
- Network tools → Home Assistant REST sensor: exposes scan results
- CUPS print server → Home Assistant user: shares printers
- LLM clients → LiteLLM gateway: sends API requests
- LiteLLM gateway → Bundled PostgreSQL: stores keys and logs
- Secrets sync → Home Assistant user: writes synced secrets
- IaC operator → IaC HTTP API: triggers plans
- IaC HTTP API → Repository checkout: clones repository
- Repository checkout → Git repository: fetches source
- IaC HTTP API → Run execution: queues run
- Run execution → OpenTofu / Terraform: runs plan or apply
- Run execution → State backends: uses backend
- State backends → R2, S3, or local state: persists state
- Run execution → Run records: records run
- Gatus monitoring → Host monitor: monitors status