feat(notify-bridge): phase 9 - HAOS integration planning

Architecture documentation for HAOS integration with Notify Bridge: - Polling-based event stream API (recommended for Phase 1) - WebSocket option for future real-time enhancement - Feature obsolescence analysis: what moves to Bridge vs stays in HAOS - New HAOS integration flow: Bridge URL -> JWT auth -> poll events - Entity mapping: sensors, binary sensors, cameras, buttons - API contract: /api/events/stream, /api/trackers/{id}/state - 4-phase migration path from direct Immich to Bridge client Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-19 23:55:56 +03:00
parent 08814e9ae2
commit 786fe5ec3d
1 changed files with 155 additions and 0 deletions
@@ -0,0 +1,155 @@
+# HAOS Integration Architecture
+
+## Overview
+
+The existing Home Assistant (HAOS) Immich Album Watcher integration will connect to
+Notify Bridge as a client, receiving events and state updates via the Bridge's API.
+
+## Communication Options
+
+### Option A: Polling (Recommended for Phase 1)
+
+HAOS integration polls the Bridge API at regular intervals for new events.
+
+```
+GET /api/events/stream?tracker_ids=1,2,3&since=2026-03-19T00:00:00Z
+Authorization: Bearer <jwt>
+```
+
+**Pros:** Simple, stateless, works through firewalls, NAT-friendly.
+**Cons:** Latency up to poll interval, extra API calls.
+
+### Option B: WebSocket (Future Enhancement)
+
+HAOS maintains a persistent WebSocket connection to the Bridge.
+
+```
+WS /api/events/ws?tracker_ids=1,2,3
+Authorization: Bearer <jwt>
+```
+
+**Pros:** Real-time, efficient for frequent events.
+**Cons:** Connection management, reconnection logic needed.
+
+### Recommendation
+
+Start with **Polling** (Option A) for simplicity and reliability. Add WebSocket
+support later as an optional real-time upgrade.
+
+## HAOS Integration Simplification
+
+### Features that become OBSOLETE (handled by Bridge):
+
+- Direct Immich API calls (Bridge handles provider communication)
+- Album change detection (Bridge detects changes via provider abstraction)
+- Telegram sending logic (Bridge dispatches notifications)
+- Template rendering (Bridge renders Jinja2 templates)
+- Notification queue / quiet hours (Bridge manages scheduling)
+
+### Features that REMAIN in HAOS:
+
+- **HA entities**: sensors, binary sensors, cameras, buttons
+- **HA events**: fired from Bridge events for automations
+- **Config flow**: now connects to Bridge URL instead of Immich directly
+- **DataUpdateCoordinator**: polls Bridge API instead of Immich API
+- **Share link management**: may stay as direct pass-through for responsiveness
+
+### New HAOS Integration Flow
+
+```
+1. User configures Bridge URL + credentials in HAOS config flow
+2. Integration authenticates with Bridge API (JWT)
+3. Integration discovers available trackers from Bridge
+4. DataUpdateCoordinator polls /api/events/stream for new events
+5. On event: fires HA event, updates sensor entities
+6. HA automations react to events as before
+```
+
+## Impact on Current HAOS Entities
+
+### Sensors (per tracked collection)
+
+| Current | New Source | Notes |
+|---------|-----------|-------|
+| Album ID | Bridge tracker state | Same data, different source |
+| Asset Count | Bridge tracker state | Polled from Bridge |
+| Photo/Video Count | Bridge tracker state | |
+| Last Updated | Bridge event timestamp | |
+| Public/Protected URL | Bridge provider (pass-through) | May need direct Immich call |
+
+### Binary Sensor
+
+- "New Assets" indicator: triggered by Bridge `assets_added` event
+
+### Camera
+
+- Thumbnail: still needs direct Immich API call (binary data)
+- Option: Bridge could expose a thumbnail proxy endpoint
+
+### Buttons
+
+- Create/Delete share links: pass through to Bridge provider API
+- Bridge would need `/api/providers/{id}/actions` endpoint
+
+## API Contract
+
+### Event Stream (Polling)
+
+```http
+GET /api/events/stream?tracker_ids=1,2&since=2026-03-19T00:00:00Z
+Authorization: Bearer <jwt>
+
+Response 200:
+{
+  "events": [
+    {
+      "id": 42,
+      "tracker_id": 1,
+      "event_type": "assets_added",
+      "provider_type": "immich",
+      "collection_id": "abc-123",
+      "collection_name": "Vacation 2026",
+      "timestamp": "2026-03-19T14:30:00Z",
+      "details": {
+        "added_count": 3,
+        "removed_count": 0
+      }
+    }
+  ],
+  "last_event_id": 42
+}
+```
+
+### Tracker State
+
+```http
+GET /api/trackers/{id}/state
+Authorization: Bearer <jwt>
+
+Response 200:
+{
+  "tracker_id": 1,
+  "provider_type": "immich",
+  "collections": [
+    {
+      "id": "abc-123",
+      "name": "Vacation 2026",
+      "asset_count": 150,
+      "last_updated": "2026-03-19T14:30:00Z"
+    }
+  ]
+}
+```
+
+## Migration Path
+
+1. **Phase 1**: Bridge runs alongside existing HAOS integration (no changes to HAOS)
+2. **Phase 2**: New HAOS integration version connects to Bridge for events
+3. **Phase 3**: HAOS integration drops direct Immich dependency, becomes pure Bridge client
+4. **Phase 4**: Old HAOS integration code removed
+
+## Open Questions
+
+- Should Bridge expose asset thumbnails as a proxy (to avoid HAOS needing direct Immich access)?
+- Should share link management go through Bridge or stay as direct Immich calls?
+- How to handle HAOS integration discovery of Bridge instances (mDNS, manual config)?