Home Assistant -- Architecture & Project Documentation¶
Last Updated: 2026-03-06 Status: Active
1. Overview¶
This document describes the Home Assistant (HA) setup as part of the wider homelab environment. It is intended as recovery-grade documentation: after a reinstall, hardware failure, or migration, this file should be sufficient to rebuild the system with the same architecture, logic, and design decisions.
The guiding principles of this project are: - Local-first & self-hosted (no cloud dependency for core automations) - High reliability (UPS-aware, monitored, observable) - Security by design (segmented access, minimal exposure) - Recoverability (clear separation of infra vs services) - Family-friendly automation (lights, notifications, presence, safety)
2. Runtime Environment¶
2.1 Host Platform¶
- Hypervisor: Proxmox VE (4-node cluster)
- HA Deployment:
- Running on:
- Rationale:
- Full HA Supervisor support
- Snapshots at VM level
- Clean separation from other services
- Easy restore / migration to new hardware
2.2 VM Characteristics (Logical)¶
- Single-purpose VM: only Home Assistant
- No additional services or containers inside HA VM
- Networking via bridge (LAN)
3. Network & Access Model¶
3.1 Access Paths¶
Home Assistant is not directly exposed to the public internet.
Access methods: 1. LAN access - Used inside the home network 2. VPN - Primary remote access (e.g., Tailscale) 3. Tunnel (limited use) - Optional browser access (e.g., Cloudflare Tunnel)
3.2 DNS & Naming¶
- Internal DNS handled by DNS filtering service
- Local hostname resolution (e.g.
homeassistant.lan)
4. Radio & Device Integration¶
4.1 Zigbee¶
- Coordinator:
- Connected to HA VM host via USB passthrough
- Used for: sensors, lights, switches
4.2 WiFi Devices¶
- WiFi-based devices integrated directly via local integrations (no cloud where possible)
- Device types: sensors, lights, plugs, switches, cameras
4.3 Voice Assistants¶
- Google Home integrated with Home Assistant
- Used for: voice control of lights, switches, and routines
5. Scope Boundary¶
This document intentionally does not contain detailed automation logic.
All concrete automations (triggers, conditions, helpers, YAML patterns, and design decisions) are documented separately in:
This separation keeps infrastructure/architecture concerns cleanly isolated from behavior and logic.
6. Dashboards & UI¶
6.1 Dashboards¶
- Multiple dashboards
- Visibility controlled per HA user
- Family-friendly views for daily use
- Admin dashboards for debugging and testing
6.2 Controls¶
7. Infrastructure Awareness¶
7.1 UPS Integration¶
- UPS monitored via
- HA receives status via sensors
8. Observability & Reliability¶
- HA startup notifications enabled
- Integration with monitoring stack (Uptime Kuma, Healthchecks.io)
- HA is treated as a core dependency, not just a convenience service
9. Backup & Recovery Strategy¶
- VM-level snapshots via hypervisor
- HA internal backups
- External backup handled by homelab backup strategy
Recovery assumption:
If the hypervisor is restored, HA can be fully recovered from VM backup without re-pairing devices.
10. Design Decisions Summary¶
| Area | Decision | Reason |
|---|---|---|
| Deployment | HA OS in VM | Stability, snapshots, supervisor |
| Access | VPN-first | Secure, friction-free |
| Cloud | Optional only | Avoid dependency |
| Automations | Separated | Clarity, recovery, maintainability |
| Security | Helper-based alarm | Safe iteration |
| UI | Intent buttons | Family usability |
11. Future Improvements¶
- Deeper UPS-driven automation (graceful shutdowns)
- More Matter-native devices
- Wall-mounted tablets for dashboards
Status: Active