haos-hacs-immich-album-watcher/plans/phase-3-server-backend.md

Phase 3: Build Standalone Server Backend

Status: In progress Parent: primary-plan.md

---

Goal

Build a standalone FastAPI web server that provides Immich album change notifications without Home Assistant, using the shared core library from Phase 1.

---

Tech Stack

• Framework: FastAPI (async-native, OpenAPI docs)
• Database: SQLite via SQLModel (SQLAlchemy + Pydantic)
• Auth: bcrypt + JWT (multi-user, admin/user roles)
• Scheduler: APScheduler (async jobs per tracker)
• Notifications: Core TelegramClient + new WebhookClient
• Templates: Jinja2 (same syntax as HA blueprint)
• Deployment: Docker (single container, SQLite in volume)

---

Directory Structure

packages/server/
  pyproject.toml
  src/immich_watcher_server/
    __init__.py
    main.py              # FastAPI app, lifespan, static mount
    config.py            # Settings from env vars
    database/
      __init__.py
      models.py          # SQLModel table definitions
      engine.py          # Engine creation, session factory
    auth/
      __init__.py
      jwt.py             # JWT token creation/validation
      dependencies.py    # FastAPI dependency for current_user
      routes.py          # /api/auth/* endpoints
    api/
      __init__.py
      servers.py         # CRUD /api/servers/*
      trackers.py        # CRUD /api/trackers/*
      templates.py       # CRUD /api/templates/*
      targets.py         # CRUD /api/targets/*
      users.py           # CRUD /api/users/* (admin)
      status.py          # GET /api/status
    services/
      __init__.py
      scheduler.py       # APScheduler setup, job management
      watcher.py         # Album polling + change detection
      notifier.py        # Dispatch notifications (Telegram/webhook)
    webhook/
      __init__.py
      client.py          # Generic webhook POST JSON
  Dockerfile
  docker-compose.yml

---

Tasks

1. Package setup [ ]

• pyproject.toml with deps: fastapi, uvicorn, sqlmodel, pyjwt, bcrypt, apscheduler, jinja2, immich-watcher-core

2. Database models [ ]

• User: id, username, hashed_password, role (admin/user), created_at
• ImmichServer: id, user_id, name, url, api_key, external_domain, created_at
• NotificationTarget: id, user_id, type (telegram/webhook), name, config JSON, created_at
• MessageTemplate: id, user_id, name, body (Jinja2), is_default, created_at
• AlbumTracker: id, user_id, server_id FK, name, album_ids JSON, event_types JSON, target_ids JSON, template_id FK (nullable), scan_interval, enabled, quiet_hours_start, quiet_hours_end, created_at
• AlbumState: id, tracker_id FK, album_id, asset_ids JSON, last_updated
• EventLog: id, tracker_id FK, event_type, album_name, details JSON, created_at

3. Auth [ ]

• POST /api/auth/setup (create first admin, only when no users exist)
• POST /api/auth/login (returns JWT access + refresh tokens)
• GET /api/auth/me (current user info)
• JWT dependency for all protected routes

4. API endpoints [ ]

• CRUD for servers, trackers, templates, targets
• GET /api/servers/{id}/albums (proxy to Immich)
• POST /api/templates/{id}/preview (render with sample data)
• POST /api/targets/{id}/test (send test notification)
• POST /api/trackers/{id}/trigger (force check)
• GET /api/trackers/{id}/history (recent events)
• GET /api/status (dashboard data)
• CRUD /api/users (admin only)

5. Background scheduler [ ]

• APScheduler with AsyncIOScheduler
• One job per enabled tracker at its scan_interval
• Job: fetch album -> detect changes -> render template -> notify
• Start/stop jobs when trackers are created/updated/deleted

6. Notification dispatch [ ]

• TelegramClient from core (reuse)
• WebhookClient: POST JSON to configured URL with event data
• Jinja2 template rendering with same variables as blueprint

7. Docker [ ]

• Multi-stage Dockerfile (build frontend -> Python runtime)
• docker-compose.yml for standalone deployment

---

Acceptance Criteria

• Server starts, creates SQLite DB on first run
• First-run setup creates admin account
• Can add Immich server, browse albums
• Can create tracker, template, and notification target
• Scheduler polls albums and detects changes
• Telegram notifications sent on album changes
• Webhook notifications sent on album changes
• JWT auth protects all endpoints
• Docker build works