Add standalone FastAPI server backend (Phase 3)

Build a complete standalone web server for Immich album change
notifications, independent of Home Assistant. Uses the shared
core library from Phase 1.

Server features:
- FastAPI with async SQLite (SQLModel + aiosqlite)
- Multi-user auth with JWT (admin/user roles, setup wizard)
- CRUD APIs: Immich servers, album trackers, message templates,
  notification targets (Telegram + webhook), user management
- APScheduler background polling per tracker
- Jinja2 template rendering with live preview
- Album browser proxied from Immich API
- Event logging and dashboard status endpoint
- Docker deployment (single container, SQLite in volume)

39 API routes, 14 integration tests passing.

Also adds Phase 6 (Claude AI Telegram bot enhancement) to the
primary plan as an optional future phase.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

packages/server/src/immich_watcher_server/services/__init__.py

@@ -0,0 +1 @@
+"""Background services package."""

packages/server/src/immich_watcher_server/services/notifier.py

@@ -0,0 +1,128 @@
+"""Notification dispatch service."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import aiohttp
+import jinja2
+
+from immich_watcher_core.telegram.client import TelegramClient
+
+from ..database.models import MessageTemplate, NotificationTarget
+from ..webhook.client import WebhookClient
+
+_LOGGER = logging.getLogger(__name__)
+
+# Default template used when no custom template is configured
+DEFAULT_TEMPLATE = (
+    "{{ added_count }} new item(s) added to album \"{{ album_name }}\"."
+    "{% if people %}\nPeople: {{ people | join(', ') }}{% endif %}"
+)
+
+
+def render_template(template_body: str, context: dict[str, Any]) -> str:
+    """Render a Jinja2 template with the given context."""
+    env = jinja2.Environment(autoescape=False)
+    tmpl = env.from_string(template_body)
+    return tmpl.render(**context)
+
+
+async def send_notification(
+    target: NotificationTarget,
+    event_data: dict[str, Any],
+    template: MessageTemplate | None = None,
+) -> dict[str, Any]:
+    """Send a notification to a target using event data.
+
+    Args:
+        target: Notification destination (telegram or webhook)
+        event_data: Album change event data (album_name, added_count, etc.)
+        template: Optional message template (uses default if None)
+    """
+    template_body = template.body if template else DEFAULT_TEMPLATE
+    try:
+        message = render_template(template_body, event_data)
+    except jinja2.TemplateError as e:
+        _LOGGER.error("Template rendering failed: %s", e)
+        message = f"Album changed: {event_data.get('album_name', 'unknown')}"
+
+    if target.type == "telegram":
+        return await _send_telegram(target, message, event_data)
+    elif target.type == "webhook":
+        return await _send_webhook(target, message, event_data)
+    else:
+        return {"success": False, "error": f"Unknown target type: {target.type}"}
+
+
+async def send_test_notification(target: NotificationTarget) -> dict[str, Any]:
+    """Send a test notification to verify target configuration."""
+    test_data = {
+        "album_name": "Test Album",
+        "added_count": 1,
+        "removed_count": 0,
+        "change_type": "assets_added",
+        "people": [],
+        "added_assets": [],
+    }
+
+    if target.type == "telegram":
+        return await _send_telegram(
+            target, "Test notification from Immich Watcher", test_data
+        )
+    elif target.type == "webhook":
+        return await _send_webhook(
+            target, "Test notification from Immich Watcher", test_data
+        )
+    return {"success": False, "error": f"Unknown target type: {target.type}"}
+
+
+async def _send_telegram(
+    target: NotificationTarget, message: str, event_data: dict[str, Any]
+) -> dict[str, Any]:
+    """Send notification via Telegram."""
+    config = target.config
+    bot_token = config.get("bot_token")
+    chat_id = config.get("chat_id")
+
+    if not bot_token or not chat_id:
+        return {"success": False, "error": "Missing bot_token or chat_id in target config"}
+
+    async with aiohttp.ClientSession() as session:
+        client = TelegramClient(session, bot_token)
+
+        # Build assets list from event data for media sending
+        assets = []
+        for asset in event_data.get("added_assets", []):
+            url = asset.get("download_url") or asset.get("url")
+            if url:
+                asset_type = "video" if asset.get("type") == "VIDEO" else "photo"
+                assets.append({"url": url, "type": asset_type})
+
+        return await client.send_notification(
+            chat_id=str(chat_id),
+            caption=message,
+            assets=assets if assets else None,
+        )
+
+
+async def _send_webhook(
+    target: NotificationTarget, message: str, event_data: dict[str, Any]
+) -> dict[str, Any]:
+    """Send notification via webhook."""
+    config = target.config
+    url = config.get("url")
+    headers = config.get("headers", {})
+
+    if not url:
+        return {"success": False, "error": "Missing url in target config"}
+
+    payload = {
+        "message": message,
+        "event": event_data,
+    }
+
+    async with aiohttp.ClientSession() as session:
+        client = WebhookClient(session, url, headers)
+        return await client.send(payload)

packages/server/src/immich_watcher_server/services/scheduler.py

@@ -0,0 +1,99 @@
+"""Background job scheduler for album polling."""
+
+from __future__ import annotations
+
+import logging
+
+from apscheduler.schedulers.asyncio import AsyncIOScheduler
+from apscheduler.triggers.interval import IntervalTrigger
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from ..database.engine import get_engine
+from ..database.models import AlbumTracker
+from .watcher import check_tracker
+
+_LOGGER = logging.getLogger(__name__)
+
+_scheduler: AsyncIOScheduler | None = None
+
+
+def get_scheduler() -> AsyncIOScheduler:
+    """Get the global scheduler instance."""
+    global _scheduler
+    if _scheduler is None:
+        _scheduler = AsyncIOScheduler()
+    return _scheduler
+
+
+async def start_scheduler() -> None:
+    """Start the scheduler and load all enabled trackers."""
+    scheduler = get_scheduler()
+
+    engine = get_engine()
+    async with AsyncSession(engine) as session:
+        result = await session.exec(
+            select(AlbumTracker).where(AlbumTracker.enabled == True)  # noqa: E712
+        )
+        trackers = result.all()
+
+    for tracker in trackers:
+        _add_tracker_job(scheduler, tracker.id, tracker.scan_interval)
+
+    scheduler.start()
+    _LOGGER.info("Scheduler started with %d tracker jobs", len(trackers))
+
+
+async def stop_scheduler() -> None:
+    """Stop the scheduler."""
+    scheduler = get_scheduler()
+    if scheduler.running:
+        scheduler.shutdown(wait=False)
+        _LOGGER.info("Scheduler stopped")
+
+
+def add_tracker_job(tracker_id: int, scan_interval: int) -> None:
+    """Add or update a scheduler job for a tracker."""
+    scheduler = get_scheduler()
+    _add_tracker_job(scheduler, tracker_id, scan_interval)
+
+
+def remove_tracker_job(tracker_id: int) -> None:
+    """Remove a scheduler job for a tracker."""
+    scheduler = get_scheduler()
+    job_id = f"tracker_{tracker_id}"
+    if scheduler.get_job(job_id):
+        scheduler.remove_job(job_id)
+        _LOGGER.debug("Removed scheduler job for tracker %d", tracker_id)
+
+
+def _add_tracker_job(
+    scheduler: AsyncIOScheduler, tracker_id: int, scan_interval: int
+) -> None:
+    """Add or replace a scheduler job."""
+    job_id = f"tracker_{tracker_id}"
+
+    # Remove existing job if present
+    if scheduler.get_job(job_id):
+        scheduler.remove_job(job_id)
+
+    scheduler.add_job(
+        _run_tracker_check,
+        trigger=IntervalTrigger(seconds=scan_interval),
+        id=job_id,
+        args=[tracker_id],
+        replace_existing=True,
+        max_instances=1,
+    )
+    _LOGGER.debug(
+        "Scheduled tracker %d every %d seconds", tracker_id, scan_interval
+    )
+
+
+async def _run_tracker_check(tracker_id: int) -> None:
+    """Run a single tracker check (called by scheduler)."""
+    try:
+        result = await check_tracker(tracker_id)
+        _LOGGER.debug("Tracker %d check result: %s", tracker_id, result)
+    except Exception:
+        _LOGGER.exception("Error checking tracker %d", tracker_id)

packages/server/src/immich_watcher_server/services/watcher.py

@@ -0,0 +1,208 @@
+"""Album watcher service - polls Immich and detects changes."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timezone
+from typing import Any
+
+import aiohttp
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+from sqlalchemy.ext.asyncio import AsyncEngine
+
+from immich_watcher_core.asset_utils import build_asset_detail, get_any_url
+from immich_watcher_core.change_detector import detect_album_changes
+from immich_watcher_core.immich_client import ImmichApiError, ImmichClient
+from immich_watcher_core.models import AlbumChange, AlbumData
+
+from ..database.engine import get_engine
+from ..database.models import (
+    AlbumState,
+    AlbumTracker,
+    EventLog,
+    ImmichServer,
+    MessageTemplate,
+    NotificationTarget,
+)
+from .notifier import send_notification
+
+_LOGGER = logging.getLogger(__name__)
+
+
+async def check_tracker(tracker_id: int) -> dict[str, Any]:
+    """Check a single tracker for album changes.
+
+    Called by the scheduler or manually via API trigger.
+    """
+    engine = get_engine()
+    async with AsyncSession(engine) as session:
+        tracker = await session.get(AlbumTracker, tracker_id)
+        if not tracker or not tracker.enabled:
+            return {"skipped": True, "reason": "disabled or not found"}
+
+        server = await session.get(ImmichServer, tracker.server_id)
+        if not server:
+            return {"error": "Server not found"}
+
+        results = []
+        async with aiohttp.ClientSession() as http_session:
+            client = ImmichClient(http_session, server.url, server.api_key)
+
+            # Fetch server config for external domain
+            await client.get_server_config()
+            users_cache = await client.get_users()
+
+            for album_id in tracker.album_ids:
+                result = await _check_album(
+                    session, http_session, client, tracker, album_id, users_cache
+                )
+                results.append(result)
+
+        await session.commit()
+        return {"albums_checked": len(tracker.album_ids), "results": results}
+
+
+async def _check_album(
+    session: AsyncSession,
+    http_session: aiohttp.ClientSession,
+    client: ImmichClient,
+    tracker: AlbumTracker,
+    album_id: str,
+    users_cache: dict[str, str],
+) -> dict[str, Any]:
+    """Check a single album for changes."""
+    try:
+        album = await client.get_album(album_id, users_cache)
+    except ImmichApiError as err:
+        _LOGGER.error("Failed to fetch album %s: %s", album_id, err)
+        return {"album_id": album_id, "error": str(err)}
+
+    if album is None:
+        return {"album_id": album_id, "status": "not_found"}
+
+    # Load previous state
+    result = await session.exec(
+        select(AlbumState).where(
+            AlbumState.tracker_id == tracker.id,
+            AlbumState.album_id == album_id,
+        )
+    )
+    state = result.first()
+
+    if state is None:
+        # First check - save state, no change detection
+        state = AlbumState(
+            tracker_id=tracker.id,
+            album_id=album_id,
+            asset_ids=list(album.asset_ids),
+            pending_asset_ids=[],
+            last_updated=datetime.now(timezone.utc),
+        )
+        session.add(state)
+        return {"album_id": album_id, "status": "initialized", "asset_count": album.asset_count}
+
+    # Build previous AlbumData from persisted state for change detection
+    previous_asset_ids = set(state.asset_ids)
+    pending = set(state.pending_asset_ids)
+
+    # Create a minimal previous AlbumData for comparison
+    prev_album = AlbumData(
+        id=album_id,
+        name=album.name,  # Use current name (rename detection compares)
+        asset_count=len(previous_asset_ids),
+        photo_count=0,
+        video_count=0,
+        created_at=album.created_at,
+        updated_at="",
+        shared=album.shared,  # Use current (sharing detection compares)
+        owner=album.owner,
+        thumbnail_asset_id=None,
+        asset_ids=previous_asset_ids,
+    )
+
+    # Detect changes
+    change, updated_pending = detect_album_changes(prev_album, album, pending)
+
+    # Update persisted state
+    state.asset_ids = list(album.asset_ids)
+    state.pending_asset_ids = list(updated_pending)
+    state.last_updated = datetime.now(timezone.utc)
+    session.add(state)
+
+    if change is None:
+        return {"album_id": album_id, "status": "no_changes"}
+
+    # Check if this event type is tracked
+    if change.change_type not in tracker.event_types and "changed" not in tracker.event_types:
+        return {"album_id": album_id, "status": "filtered", "change_type": change.change_type}
+
+    # Log the event
+    shared_links = await client.get_shared_links(album_id)
+    event_data = _build_event_data(change, album, client.external_url, shared_links)
+
+    event_log = EventLog(
+        tracker_id=tracker.id,
+        event_type=change.change_type,
+        album_id=album_id,
+        album_name=album.name,
+        details={"added_count": change.added_count, "removed_count": change.removed_count},
+    )
+    session.add(event_log)
+
+    # Send notifications to all configured targets
+    for target_id in tracker.target_ids:
+        target = await session.get(NotificationTarget, target_id)
+        if not target:
+            continue
+
+        template = None
+        if tracker.template_id:
+            template = await session.get(MessageTemplate, tracker.template_id)
+
+        try:
+            await send_notification(target, event_data, template)
+        except Exception:
+            _LOGGER.exception("Failed to send notification to target %d", target_id)
+
+    return {
+        "album_id": album_id,
+        "status": "changed",
+        "change_type": change.change_type,
+        "added_count": change.added_count,
+        "removed_count": change.removed_count,
+    }
+
+
+def _build_event_data(
+    change: AlbumChange,
+    album: AlbumData,
+    external_url: str,
+    shared_links: list,
+) -> dict[str, Any]:
+    """Build event data dict for template rendering and webhook payload."""
+    added_details = []
+    for asset in change.added_assets:
+        if asset.is_processed:
+            added_details.append(
+                build_asset_detail(asset, external_url, shared_links, include_thumbnail=False)
+            )
+
+    album_url = get_any_url(external_url, shared_links)
+
+    return {
+        "album_id": change.album_id,
+        "album_name": change.album_name,
+        "album_url": album_url or "",
+        "change_type": change.change_type,
+        "added_count": change.added_count,
+        "removed_count": change.removed_count,
+        "added_assets": added_details,
+        "removed_assets": change.removed_asset_ids,
+        "people": list(album.people),
+        "shared": album.shared,
+        "old_name": change.old_name,
+        "new_name": change.new_name,
+        "old_shared": change.old_shared,
+        "new_shared": change.new_shared,
+    }