manage/openspec/changes/service-registry/apply-progress.md

Apply Progress: Runtime Service Registry

Change: service-registry Apply run: PR 1 / Slice 1 — Backend service foundation Date: 2026-06-19

Completed tasks (Slice 1)

• 1.1 Add encryption helper (services/secrets.py)
• 1.2 Add integrations base classes (integrations/base.py)
• 1.3 Add five service definitions + registry
• 1.4 Add services + service_task_runs tables + store CRUD with cascade delete
• 1.5 Add service Pydantic models + /api/services* router
• 1.6 Validate MANAGE_ENCRYPTION_KEY on startup
• 1.7 Add backend tests (tests/test_services.py)
• 1.8 Verify (ruff + pytest green)

Files changed (Slice 1)

New files

• backend/src/media_library_viewer_api/integrations/__init__.py — package marker.
• backend/src/media_library_viewer_api/integrations/base.py — ServiceConfigBase, WidgetConfigBase, SecretField, WidgetKind, ServiceDefinition, widget_kind(), validate_config().
• backend/src/media_library_viewer_api/integrations/{grafana,prometheus,jellyfin,nextcloud,ssh_tasks}.py — one Pydantic-config + widget-config definition per service.
• backend/src/media_library_viewer_api/integrations/registry.py — closed SERVICE_DEFINITIONS + helpers.
• backend/src/media_library_viewer_api/services/secrets.py — Fernet encrypt/decrypt
  • key validation.
• backend/src/media_library_viewer_api/models/services.py — request/response models.
• backend/src/media_library_viewer_api/routers/services.py — /api/services/types
  • /api/services/instances CRUD.
• backend/tests/test_services.py — 25 tests.

Modified files

• backend/src/media_library_viewer_api/services/settings_store.py — services and service_task_runs tables; service CRUD; cascade delete (defensive against the not-yet-present dashboard_widgets.service_id column); task-run history helpers.
• backend/src/media_library_viewer_api/main.py — register services_router; validate encryption key on startup.
• backend/pyproject.toml — declare cryptography>=42.0 direct dependency.
• docker-compose.yml, docker-compose.dev.yml, .env.example, README.md — require and document MANAGE_ENCRYPTION_KEY.

Verification (Slice 1)

cd backend
.venv/bin/ruff check .                                      # All checks passed
PYTHONPATH=src .venv/bin/python -m pytest                   # 225 passed
cd ../frontend
npm run lint                                                # 0 errors
npm run build                                               # success

Smoke: encryption round-trip OK; missing MANAGE_ENCRYPTION_KEY raises on startup.

Deviations from design

• Service-config and widget-config schemas are derived from Pydantic models (model_json_schema()), matching the user's "proper pydantic config definitions" request. The design's hand-written JSON schemas were replaced by model-derived ones.
• Service-table CRUD lives on SettingsStore (not a separate service_store.py) to match how widgets/saved_tasks/ssh_keys are already handled there. This keeps a single store owner for all tables.
• The cascade delete defensively checks for dashboard_widgets.service_id (added in Slice 2) so Slice 1 stays green without the column.

Remaining work

• Slice 2: Backend widget rebind to services (add service_id/widget_kind, refactor adapters to take a ServiceRecord, retire old widget registry, SSH run logging).
• Slice 3: Frontend services runtime (types, API, hooks, frontend registry, service pages, route swap).
• Slice 4: Dashboard picker, settings rework, remove grafana_url/prometheus_url env vars, stop default seeding, docs + changelog.