manage/openspec/changes/archive/jellyfin-service-registry/design.md

Design — Jellyfin service-registry migration (completion)

Change: jellyfin-service-registry Phase: design Date: 2026-06-23

Current state

• Jellyfin/Jellyseerr service definitions exist in integrations/jellyfin.py and integrations/jellyseerr.py.
• dependencies.py resolves Jellyfin clients from service records via jellyfin_service_id.
• Frontend pages already select Jellyfin services via useServiceInstances("jellyfin").
• settings_store.py still defaults machine services to ["monitoring", "files", "jellyfin"] and persists media_root / path_prefix.
• MonitoringMachine / MonitoringMachineInput types still include media_root and path_prefix.
• Settings.tsx still renders media_root and path_prefix inputs and lists jellyfin as a service option.
• path_utils.py still has path-mapping helpers, but the callers in files.py no longer depend on machine-level media_root/path_prefix.

Target state

Backend

• DEFAULT_SERVICES becomes ["monitoring", "files"].
• settings_store.py drops media_root and path_prefix from _normalize_machine_payload, _row_to_machine, the machine table schema, and default seeding.
• Add DROP TABLE IF EXISTS ... or ALTER TABLE DROP COLUMN cleanup as needed for existing databases (SQLite has limited DROP COLUMN support; prefer table rebuild or leave harmless columns).
• path_utils.py is reviewed; if no callers remain, delete the module. If callers remain, ensure they do not reference machine fields.
• routers/files.py confirmed to not read machine media_root/path_prefix.
• Tests updated to remove media_root/path_prefix from fixtures.

Frontend

• Remove media_root and path_prefix from MonitoringMachine and MonitoringMachineInput in types/index.ts.
• Remove jellyfin from the machine services multi-select in Settings.tsx.
• Remove media_root and path_prefix inputs from the machine editor.
• Update emptyMachine() to not include these fields.
• Update tests/fixtures.

Docs

• docs/REQUIREMENTS.md — update the machine config description to remove Jellyfin/path-prefix fields.
• CHANGELOG.md — breaking note about removed machine fields.

Slices

1. Backend cleanup — settings_store.py, config.py (if any env vars), path_utils.py, tests.
2. Frontend cleanup — types, Settings.tsx, tests.
3. Docs + changelog.

Risks

• Existing DB rows may have media_root/path_prefix values; dropping columns is safe but irreversible. Backups recommended.
• path_utils.py may still be referenced by archive code; verify only live code is affected.