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