alexei.dolgolyov
d0783d0b6a
Some checks failed
Validate / Hassfest (push) Has been cancelled
Extract HA-independent logic from the integration into packages/core/ as a standalone Python library (immich-watcher-core). This is the first phase of restructuring the project to support a standalone web app alongside the existing HAOS integration. Core library modules: - models: SharedLinkInfo, AssetInfo, AlbumData, AlbumChange dataclasses - immich_client: Async Immich API client (aiohttp, session-injected) - change_detector: Pure function for album change detection - asset_utils: Filtering, sorting, URL building utilities - telegram/client: Full Telegram Bot API (text, photo, video, media groups) - telegram/cache: File ID cache with pluggable storage backend - telegram/media: Media size checks, URL extraction, group splitting - notifications/queue: Persistent notification queue - storage: StorageBackend protocol + JSON file implementation All modules have zero Home Assistant imports. 50 unit tests passing. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
215 lines
9.2 KiB
Markdown
215 lines
9.2 KiB
Markdown
# Immich Watcher: Standalone Web App + Shared Core Architecture
|
|
|
|
**Status**: Planning
|
|
**Created**: 2026-03-19
|
|
|
|
---
|
|
|
|
## Context
|
|
|
|
The current `immich_album_watcher` HA integration contains ~3,600 lines of tightly coupled code: Immich API client, change detection, Telegram notifications, and HA entities/services. A separate HA Blueprint (~2,000 lines) adds message templating, filtering, scheduled notifications, and memory mode.
|
|
|
|
**Goal**: Enable Immich album change notifications **without Home Assistant** via a standalone web application, while keeping the HAOS integration functional and sharing as much logic as possible.
|
|
|
|
---
|
|
|
|
## Decisions
|
|
|
|
| Decision | Choice | Rationale |
|
|
|---|---|---|
|
|
| Architecture | Hybrid (Option C) | HAOS standalone with shared core lib, optional server sync. No breaking changes for HA-only users. |
|
|
| Frontend | SvelteKit + Shadcn-svelte | Small bundle, fast, calm UI aesthetic. Good fit for self-hosted. |
|
|
| Notifications | Telegram + Generic webhook | Telegram from existing code. Webhook enables Discord/Slack/ntfy/custom. |
|
|
| Auth | Multi-user (admin/user roles) | Supports shared Immich servers. Admin manages servers/users, users manage own trackers. |
|
|
| Backend | FastAPI + SQLite + APScheduler | Async-native Python, zero external DB deps, proven scheduler. |
|
|
|
|
---
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
immich-watcher/
|
|
packages/
|
|
core/ # Shared Python library
|
|
pyproject.toml
|
|
src/immich_watcher_core/
|
|
immich_client.py # Immich API (from coordinator.py)
|
|
models.py # AssetInfo, AlbumData, AlbumChange, SharedLinkInfo
|
|
change_detector.py # Change detection (from coordinator.py)
|
|
telegram/
|
|
client.py # Telegram Bot API (from sensor.py)
|
|
cache.py # File cache with pluggable backend
|
|
media.py # Media download, size checks, group splitting
|
|
webhook/
|
|
client.py # Generic webhook notification provider
|
|
templates.py # Jinja2 template engine
|
|
storage.py # Abstract storage protocol + SQLite impl
|
|
constants.py # Shared constants (from const.py)
|
|
tests/
|
|
|
|
server/ # Standalone FastAPI app
|
|
pyproject.toml
|
|
src/immich_watcher_server/
|
|
main.py # FastAPI entry point
|
|
database/models.py # SQLModel ORM
|
|
database/migrations/ # Alembic
|
|
api/ # REST endpoints
|
|
services/
|
|
scheduler.py # APScheduler background polling
|
|
watcher.py # Album polling orchestrator
|
|
notifier.py # Notification dispatch
|
|
Dockerfile
|
|
docker-compose.yml
|
|
|
|
haos/ # Home Assistant integration (moved)
|
|
custom_components/immich_album_watcher/
|
|
... (refactored to use core library)
|
|
hacs.json
|
|
|
|
frontend/ # SvelteKit web UI source
|
|
package.json
|
|
src/
|
|
dist/ # Built static files served by FastAPI
|
|
|
|
plans/ # This folder
|
|
README.md
|
|
LICENSE
|
|
```
|
|
|
|
---
|
|
|
|
## Shared Core Library Extractions
|
|
|
|
| Core Module | Source File | What Gets Extracted |
|
|
|---|---|---|
|
|
| `immich_client.py` | coordinator.py | All `/api/` calls, session injection via constructor |
|
|
| `models.py` | coordinator.py L66-326 | Dataclasses (already HA-independent) |
|
|
| `change_detector.py` | coordinator.py L979-1066 | `detect_album_changes()` pure function |
|
|
| `telegram/client.py` | sensor.py (~1200 lines) | Full Telegram Bot API: send_message/photo/video/media_group |
|
|
| `telegram/cache.py` | storage.py | TelegramFileCache with `CacheBackend` protocol |
|
|
| `templates.py` | NEW (from blueprint logic) | Jinja2 renderer with ~40 variables matching blueprint |
|
|
| `storage.py` | storage.py | Abstract protocol + SQLite implementation |
|
|
| `webhook/client.py` | NEW | Generic webhook POST JSON with event data |
|
|
|
|
The `ImmichClient` accepts an `aiohttp.ClientSession` in constructor -- HA provides its managed session, standalone creates its own.
|
|
|
|
---
|
|
|
|
## Standalone Server Design
|
|
|
|
### Backend: FastAPI + SQLite + APScheduler
|
|
|
|
**Database tables**: `users`, `immich_servers`, `notification_targets`, `message_templates`, `album_trackers`, `album_states`, `telegram_cache`, `notification_queue`
|
|
|
|
**Key API endpoints**:
|
|
- `POST /api/auth/setup` / `POST /api/auth/login` -- JWT auth
|
|
- `CRUD /api/servers` -- Immich server connections
|
|
- `GET /api/servers/{id}/albums` -- Fetch album list from Immich
|
|
- `CRUD /api/trackers` -- Album trackers (album selection, event types, template overrides, targets)
|
|
- `CRUD /api/templates` -- Message templates with preview
|
|
- `CRUD /api/targets` -- Notification targets (Telegram chats, webhooks)
|
|
- `CRUD /api/users` -- User management (admin only)
|
|
- `GET /api/status` -- Dashboard data
|
|
|
|
**Background**: APScheduler runs one job per tracker at its scan interval. Each job: fetch album -> detect changes -> render template -> dispatch notification.
|
|
|
|
### Frontend: SvelteKit + Shadcn-svelte
|
|
|
|
**Pages**:
|
|
1. **Setup wizard** -- First-run: create admin account, connect Immich server
|
|
2. **Login** -- Username/password
|
|
3. **Dashboard** -- Active trackers overview, recent events timeline, server status
|
|
4. **Servers** -- Add/edit Immich server connections (URL + API key validation)
|
|
5. **Trackers** -- Create/edit album trackers:
|
|
- Album picker (multi-select, fetched from Immich)
|
|
- Event type toggles (assets added/removed, renamed, sharing changed, deleted)
|
|
- Notification target selection
|
|
- Template selection or per-tracker override
|
|
- Scan interval, quiet hours
|
|
6. **Templates** -- Jinja2 template editor:
|
|
- CodeMirror with Jinja2 syntax highlighting
|
|
- Live preview with sample album data
|
|
- Variable reference sidebar
|
|
- Default templates for common use cases
|
|
7. **Targets** -- Manage notification destinations (Telegram chats, webhooks)
|
|
8. **Users** -- User management (admin only)
|
|
9. **Settings** -- Global defaults
|
|
|
|
### Auth: Multi-user, bcrypt + JWT
|
|
|
|
- Multiple user accounts with admin/user roles
|
|
- Admin: full access (user management, server configuration)
|
|
- User: manage own trackers, templates, and targets
|
|
- First-run setup creates initial admin account
|
|
|
|
### Deployment: Single Docker container, SQLite in mounted volume
|
|
|
|
---
|
|
|
|
## HAOS Integration Changes
|
|
|
|
The integration gets refactored to delegate to core:
|
|
|
|
```python
|
|
# coordinator.py becomes thin wrapper
|
|
class ImmichAlbumWatcherCoordinator(DataUpdateCoordinator):
|
|
def __init__(self, ...):
|
|
self._client = ImmichClient(session, url, api_key) # from core
|
|
|
|
async def _async_update_data(self):
|
|
album = await self._client.get_album(self._album_id)
|
|
change = detect_album_changes(old, album, pending) # from core
|
|
if change: self._fire_events(change, album) # HA-specific
|
|
return album
|
|
|
|
# sensor.py Telegram methods delegate to core
|
|
async def _execute_telegram_notification(self, ...):
|
|
telegram = TelegramClient(session, token, cache) # from core
|
|
return await telegram.send_notification(...)
|
|
```
|
|
|
|
---
|
|
|
|
## Phases
|
|
|
|
> **Rule**: Before starting work on any phase, create a detailed trackable subplan at `plans/phase-N-<name>.md` with granular tasks, specific files to create/modify, and acceptance criteria. Do not begin implementation until the subplan is reviewed.
|
|
|
|
### Phase 1: Extract Core Library `[x]`
|
|
- Extract models, Immich client, change detection, Telegram client, cache into `packages/core/`
|
|
- Write unit tests for all extracted modules
|
|
- **Subplan**: `plans/phase-1-core-library.md`
|
|
|
|
### Phase 2: Wire Core into HAOS Integration `[ ]`
|
|
- Move integration to `packages/haos/`
|
|
- Refactor coordinator.py, sensor.py, storage.py to use core library
|
|
- Update manifest.json, hacs.json for new structure
|
|
- Verify identical behavior with real Immich server
|
|
- **Subplan**: `plans/phase-2-haos-refactor.md`
|
|
|
|
### Phase 3: Build Server Backend `[ ]`
|
|
- FastAPI app with database, scheduler, API endpoints
|
|
- Telegram + webhook notification providers
|
|
- Jinja2 template engine with variable system matching blueprint
|
|
- **Subplan**: `plans/phase-3-server-backend.md`
|
|
|
|
### Phase 4: Build Frontend `[ ]`
|
|
- SvelteKit app with all pages (setup, dashboard, trackers, templates, targets, users)
|
|
- Template editor with live preview
|
|
- Album picker connected to Immich API
|
|
- **Subplan**: `plans/phase-4-frontend.md`
|
|
|
|
### Phase 5: HAOS-Server Sync (Optional) `[ ]`
|
|
- Add optional server URL to HA config flow
|
|
- Implement tracker/template config sync
|
|
- **Subplan**: `plans/phase-5-haos-server-sync.md`
|
|
|
|
---
|
|
|
|
## Verification
|
|
|
|
1. **Core library**: Unit tests for Immich client (mocked HTTP), change detection (pure function), Telegram client (mocked API), template rendering
|
|
2. **HAOS integration**: After refactoring, verify all existing entities, services, and events work identically with a real Immich server
|
|
3. **Server backend**: API integration tests with SQLite in-memory DB, scheduler tests
|
|
4. **Frontend**: Manual testing of all pages, template editor preview, album picker
|
|
5. **End-to-end**: Docker Compose up -> create account -> connect Immich -> create tracker -> trigger album change -> verify notification received
|