notify-bridge/docs/haos-integration-architecture.md

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)

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

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)?