# Phase 5: HAOS-Server Sync (Optional)

**Status**: In progress
**Parent**: [primary-plan.md](primary-plan.md)

---

## Goal

Allow the HAOS integration to optionally connect to the standalone server, enabling:
- Syncing tracker configurations from server to HA
- Using server-managed templates for notifications
- Centralized management via the web UI while HA provides entities/automations

The connection is **additive** -- the integration works standalone without a server.

---

## Tasks

### 1. Add server URL to HA config flow `[ ]`
- Add optional `server_url` field to hub options flow
- Add optional `server_api_key` field (JWT token or API key)
- Validate connection on save

### 2. Server sync service `[ ]`
- New `sync.py` module in integration
- `async_sync_from_server()`: Fetch tracker configs from server API
- Map server trackers to HA album subentries
- Store server connection state in hub data

### 3. Server API endpoint for HA sync `[ ]`
- `GET /api/sync/trackers` -- Returns tracker configs formatted for HA consumption
- `GET /api/sync/templates/{id}/render` -- Render template with provided context
- Auth via API key header (simpler than JWT for machine-to-machine)

### 4. Bidirectional event reporting `[ ]`
- HA integration reports detected events back to server
- `POST /api/sync/events` -- HA pushes event data to server for logging
- Server dashboard shows events from both standalone polling and HA

---

## Acceptance Criteria

- [ ] Integration works identically without server URL configured
- [ ] With server URL, tracker configs can be synced
- [ ] Events detected by HA are visible in server dashboard
- [ ] Server connection failure doesn't break HA integration