Intent Map – Zero-UI Home Automation (2025)
Machine-readable design intent for AI-assisted coding.
This file describes WHAT the system is trying to accomplish and the constraints it must obey.
It does not include implementation steps.
meta: project_name: "Zero-UI Home Automation" year: 2025 principles: - "Local-first for real-time control" - "Less is more; reduce cognitive load" - "Physical controls always win" - "Apple Home is the only family UI" - "Silence by default; notify only when actionable" success_metrics: - "Family rarely opens HA UI (operator-only)" - "Lighting feels instant and never fights the user" - "Notifications approach near-zero" - "Internet outage does not break core behaviors" - "System remains maintainable and boring"
surfaces: family_ui: primary: "Apple Home" allowed_secondary: - "Physical switches (Lutron)" - "Keypads/buttons (Lutron)" disallowed: - "Home Assistant dashboards as a daily requirement" - "Mode switching via UI for normal operation" operator_ui: - "Home Assistant" - "Logs/metrics" - "Repository docs" - "Operator portal (docs + links)"
architecture: layers: physical: role: "Reality layer; must work 24/7" includes: - "Lutron Caséta switches/dimmers" - "Hardwired motion sensors" - "Hardwired door contacts" - "PoE cameras" logic: role: "Home automation brain" technology: "Home Assistant (Docker)" messaging: role: "Event transport and decoupling" technology: "MQTT (Mosquitto)" storage: role: "State history and time-series" technologies: recorder_db: "PostgreSQL" timeseries_db: "InfluxDB" intelligence: role: "Noise reduction via classification" technologies: - "Frigate (local NVR + detection)" - "Optional Coral TPU" interface: role: "Family control and visibility" technology: "Apple Home (HomeKit)" ingress: role: "External access termination and routing" technology: "Nginx Proxy Manager (Docker)" policy: - "Router forwards 80/443 to NPM only" - "Services attach to nginx-proxy_default; route by container name" - "Let’s Encrypt certs; Force SSL, HTTP/2, HSTS"
integrations: priority: - name: "Lutron Caséta" category: "lighting" requirement: "Must be instant and reliable; physical control always works." criticality: "realtime" cloud_allowed: false
- name: "Konnected (ESPHome)"
category: "wired_sensors"
requirement: "Hardwired sensors become first-class with sub-second latency."
criticality: "realtime"
cloud_allowed: false
- name: "Reolink PoE"
category: "cameras"
requirement: "Local camera feeds; stable LAN access."
criticality: "near_realtime"
cloud_allowed: false
secondary: - name: "Sense" category: "energy_monitoring" requirement: "Energy visibility; avoid notification spam." criticality: "noncritical" cloud_allowed: true
- name: "Solar Inverters (local Modbus TCP)"
category: "energy_generation"
requirement: "Prefer local polling to cloud APIs."
criticality: "near_realtime"
cloud_allowed: false
- name: "Generator"
category: "power_resilience"
requirement: "Outage awareness; generator state; actionable alerts only."
criticality: "safety"
cloud_allowed: false
- name: "Tesla"
category: "vehicle"
requirement: "State exposure is useful; must tolerate auth/API failures."
criticality: "noncritical"
cloud_allowed: true
- name: "Rivian"
category: "vehicle"
requirement: "Best-effort integration; must degrade gracefully."
criticality: "noncritical"
cloud_allowed: true
transition: - name: "Wyze Cameras" category: "cameras" requirement: "Deprecate/replace due to cloud dependence; minimize reliance." criticality: "noncritical" cloud_allowed: true strategy: "Phase out in favor of Reolink PoE; avoid building core logic on Wyze events."
data: retention: homeassistant_recorder_days: 30 timeseries_years: 3 storage_policy: - "Use PostgreSQL for HA recorder to avoid SQLite performance issues." - "Use InfluxDB for long-term time-series (solar/energy metrics)." privacy: - "Keep video local when possible." - "Expose only curated entities to Apple Home."
automation_policy: global_rules: - "One automation = one job" - "Must be explainable in one sentence" - "Must include a manual override cooldown" - "Off actions must be conservative" - "If uncertain, do nothing" - "Rate-limit all notifications" - "No novelty routines" failure_modes: - "If cloud/API is down for noncritical systems, ignore and continue." - "If sensor data is missing/unknown, default to safe no-op." - "If HA restarts, physical controls still work and system recovers automatically."
domains: lighting: goal: "Make lighting feel human, instant, and calm." triggers_preferred: - "Door opens" - "Motion detected" - "Sunset/sunrise" constraints: - "Never fight physical switches" - "Night lighting is low-impact" - "Avoid rapid toggling" notify: allowed: false
occupancy: goal: "Room-local occupancy drives local comfort behaviors." signals_primary: - "Hardwired motion" - "Door contacts" signals_secondary: - "Network presence" - "Phone presence" constraints: - "Avoid phone-only presence" - "No whole-house inferences from single sensor"
security: goal: "Awareness without chaos; explicit arming if used." constraints: - "Security-critical behavior must not depend on cloud." - "Modes (home/away/armed) must be explicit, few, and understandable." notify: allowed: true only_if_actionable: true
energy: goal: "Use energy awareness to quietly optimize comfort and cost." constraints: - "No nagging" - "Avoid oscillation" - "Prefer local polling" notify: allowed: true only_if_actionable: true examples: - "Grid outage + generator failed to start" - "Inverter offline unexpectedly"
cameras: goal: "Local visibility and low-noise alerts." constraints: - "AI filters events; uncertainty -> silence" - "Avoid motion-only alerts" notify: allowed: true only_if_actionable: true allowed_classes: - "person" - "package" - "vehicle"
vehicles: goal: "Convenient state visibility; minimal automation." constraints: - "Must tolerate API failures" - "No mission-critical automations" - "Avoid frequent polling that causes battery drain" notify: allowed: false
rollout: phases: - name: "Foundation" intent: "Deploy core on-prem logic, messaging, and storage." includes: - "Home Assistant" - "MQTT" - "PostgreSQL" - "InfluxDB" - name: "Skeleton" intent: "Bring hardwired sensors online with ESPHome." includes: - "Konnected ESPHome" - name: "Lighting" intent: "Deliver immediate family trust via instant lighting behavior." includes: - "Lutron integration" - "Entry lighting automations" - name: "Energy" intent: "Add local energy awareness and historical metrics." includes: - "Solar Modbus polling" - "Influx dashboards (operator-only)" - name: "Vision" intent: "Local cameras in Apple Home and AI noise reduction." includes: - "Scrypted" - "Frigate" - "Coral optional" - name: "Mobility" - name: "Ingress" intent: "Publish operator surfaces safely via subdomains." includes: - "Nginx Proxy Manager configured" - "teamlewis.co portal" - "docs.teamlewis.co docs" - "ai.teamlewis.co (Open WebUI)" intent: "Best-effort vehicle state integration." includes: - "Tesla Fleet proxy" - "Rivian best-effort"
explicit_non_goals:
- "Multiple family dashboards"
- "Notification-heavy motion alerts"
- "Cloud-only dependencies for lighting/security"
- "Experimental AI deciding behavior"
- "Mode explosion (too many system modes)"