manage/openspec/changes/services-as-hub-ia/tasks.md

Tasks — Services as hub IA

Change: services-as-hub-ia Phase: tasks Date: 2026-06-26

Review workload forecast

Field	Value
Estimated changed lines	~4500–6000
Chained PRs recommended	Yes (12 slices)
Chain strategy	stacked-to-main
Slice order	1–3 backend → 4 shell → 5–9 content tabs → 10 dashboards → 11 cleanup → 12 verify

Each slice is committed separately. Every slice must leave cd backend && .venv/bin/ruff check . && .venv/bin/python -m pytest and cd frontend && npm run lint && npm run build && npm run test green. Every touched page gains a Vitest case at the new route and asserts the old route 404s (where applicable).

---

Slice 1 — Backend: new service types + Jellyseerr absorption

Goal: Registry reflects the new world. No frontend change yet.

• 1.1 Add backups integration

  • Files: backend/src/media_library_viewer_api/integrations/backups.py (new), integrations/registry.py
  • Details: BackupsConfig (ingestion_label: str = "default"), no secrets, widget kind summary (move BackupsWidgetSource adapter to bind the service_id). Register in SERVICE_DEFINITIONS.

• 1.2 Add authentik integration

  • Files: integrations/authentik.py (new), registry.py
  • Details: AuthentikConfig (base_url: ServiceBaseUrl, timeout_seconds), secret api_token (required). No widget kinds yet.

• 1.3 Absorb jellyseerr into JellyfinConfig

  • Files: integrations/jellyfin.py, integrations/jellyseerr.py (delete), integrations/registry.py, integrations/__init__.py
  • Details: Add optional jellyseerr_url, jellyseerr_api_key to JellyfinConfig. Delete the jellyseerr integration module and registry entry. Update tests.

• 1.4 Jellyseerr migration

  • Files: services/settings_store.py (ensure_defaults)
  • Details: On startup, migrate existing jellyseerr rows into paired jellyfin instances per the design. Log a warning for unpaired drops.

• 1.5 Tests

  • Update backend/tests/test_services.py, test_widgets.py for the new types and the migration. Assert registry contains 8 types (alertmanager, authentik, backups, grafana, jellyfin, nextcloud, prometheus, ssh_tasks).

---

Slice 2 — Backend: Authentik directory client + endpoint

• 2.1 AuthentikClient

  • Files: clients/authentik.py (new)
  • Details: users(search, page, page_size) -> {items, total} against the Authentik directory API. Reuse the requests-session pattern from clients/jellyseerr.py. Tests: tests/test_authentik_client.py.

• 2.2 Directory endpoint

  • Files: routers/authentik_users.py (new), main.py (register router)
  • Details: GET /api/services/authentik/{service_id}/users proxies to the client, resolving the service record via the existing dependency. Tests cover not-configured + unreachable + paginated-success.

---

Slice 3 — Backend: route cleanup + backups attribution

• 3.1 Remove Users router

  • Files: routers/users.py, routers/users_impl.py (delete), main.py, dependencies.py
  • Details: Delete the Jellyfin-backed user directory + message-compose router and its deps. Update test_api.py to drop the corresponding tests.

• 3.2 Backups service attribution

  • Files: routers/backups.py, services/settings_store.py
  • Details: backup report endpoint accepts optional ?service_id=; first-wins association to an enabled backups instance when omitted. Dashboard summary
    • poller continue to work.

• 3.3 Named dashboards backend

  • Files: models/dashboards.py (new), routers/dashboards.py (new), services/settings_store.py (table + CRUD)
  • Details: named_dashboards table (id, slug, label, sort_order, payload JSON of widget+link placements). Endpoints: GET/POST/PUT/DELETE /api/dashboards. Tests in tests/test_dashboards.py.

---

Slice 4 — Frontend: top-nav generation + service-page skeleton

Goal: Data-driven nav + tab-skeleton ServicePage shell. Content tabs are stubs that say "coming soon" so the rest of the app stays green.

• 4.1 Service-type → nav-entry map

  • Files: frontend/src/integrations/navEntries.ts (new)
  • Details: Static SERVICE_TYPE_NAV_ENTRIES map (jellyfin→Media, ssh_tasks→[Files, Actions], alertmanager→Alerts, etc.). Helper to filter by configured types.

• 4.2 Data-driven nav in App.tsx

  • Files: frontend/src/App.tsx
  • Details: Replace static navItems with the memoized list from design. Add useDashboards() and combine with useServiceInstances(). Loading skeleton nav until settled. Legacy routes removed; add 404 catch-all.

• 4.3 ServicePage tab skeleton + instance switcher

  • Files: frontend/src/pages/ServicePage.tsx, new pages/service-tabs/ directory, pages/ServiceTypePage.tsx (redirect resolver)
  • Details: Refactor ServicePage to render [Overview, ...content, Widgets, Config] from serviceTabs(serviceType). Add /services/:type resolver route. Content tabs are stub components ("coming soon"). Instance switcher dropdown when siblings > 1.

• 4.4 Empty-state CTAs

  • Files: frontend/src/pages/Dashboard.tsx, pages/ServicesPage.tsx
  • Details: Dashboard shows "Add a service" CTA when no services. Services page strong empty state.

• 4.5 Tests

  • Nav-generation tests, service-page-skeleton tests, 404-on-legacy-routes tests.

---

Slice 5 — Frontend: Jellyfin content tabs (Media + Requests)

• 5.1 MediaTab

  • Files: pages/service-tabs/MediaTab.tsx (lift from pages/Media.tsx)
  • Details: Accept instance prop, pass instance.id to media hooks. Preserve the index build controls + mobile card layout. Delete the old /media route and Applications.tsx wrapper.

• 5.2 RequestsTab (Jellyseerr enrichment)

  • Files: pages/service-tabs/RequestsTab.tsx
  • Details: Source from the absorbed jellyseerr_url/jellyseerr_api_key on the Jellyfin instance. Render request-management data.

• 5.3 Tests

  • New tests for MediaTab (instance-scoped), RequestsTab. Delete old Media page tests.

---

Slice 6 — Frontend: ssh_tasks content tabs (Files + Actions)

• 6.1 FilesTab

  • Files: pages/service-tabs/FilesTab.tsx (lift from FileBrowser.impl.tsx)
  • Details: Accept instance prop. Delete old /files route + page wrapper.

• 6.2 ActionsTab

  • Files: pages/service-tabs/ActionsTab.tsx (lift from Actions.tsx)
  • Details: Accept instance prop. Delete old /actions route + page.

• 6.3 Tests

---

Slice 7 — Frontend: backups Jobs tab

• 7.1 JobsTab

  • Files: pages/service-tabs/JobsTab.tsx (lift from components/BackupsPage.tsx)
  • Details: Accept instance prop, scope queries by instance.id. Delete old /backups route + page.

• 7.2 Tests

---

Slice 8 — Frontend: Authentik Users + Messaging tabs

• 8.1 UsersTab

  • Files: pages/service-tabs/UsersTab.tsx, hooks/useAuthentikUsers.ts, api/authentik.ts
  • Details: Directory table + search, sourced from the new endpoint. No Jellyfin/Jellyseerr enrichment.

• 8.2 MessagingTab

  • Files: pages/service-tabs/MessagingTab.tsx (lift compose UI from UsersPage.impl.tsx)
  • Details: Recipient list sourced from Authentik users. Reuse the mail queue + SMTP settings. Delete the old /users route + UsersPage.

• 8.3 Tests

---

Slice 9 — Frontend: Observability split (Alerts + Links + Metrics tabs)

• 9.1 AlertsTab

  • Files: pages/service-tabs/AlertsTab.tsx (lift from ObservabilityPage.tsx)
  • Details: Alertmanager alerts view, instance-scoped. Delete old /observability route + page.

• 9.2 LinksTab + MetricsTab

  • Files: pages/service-tabs/LinksTab.tsx, pages/service-tabs/MetricsTab.tsx
  • Details: Grafana deep-links; Prometheus status + PromQL explorer. Each instance-scoped.

• 9.3 Tests

---

Slice 10 — Frontend: named dashboards

• 10.1 NamedDashboardPage

  • Files: pages/NamedDashboardPage.tsx, hooks/useDashboards.ts, api/dashboards.ts
  • Details: Render widgets + pinned service links at /d/:slug. CRUD via the new endpoints.

• 10.2 Pinned service links

  • Files: components/PinnedServiceLink.tsx, integration into the dashboard config dialog
  • Details: Shortcut variant targeting /services/:type/:id or a specific tab.

• 10.3 Dashboard management UI

  • Files: a new "Manage dashboards" entry on the Services or Settings page
  • Details: Create/rename/reorder/delete named dashboards.

• 10.4 Tests

---

Slice 11 — Cleanup + docs

• 11.1 Delete dead code

  • Files: any remaining top-level page wrappers, unused hooks, stale types.
  • Details: Confirm no references to removed routes/pages remain.

• 11.2 Update docs/REQUIREMENTS.md

  • Files: docs/REQUIREMENTS.md
  • Details: Rewrite the Information Architecture section. Document the service- type → nav-entry map, the service-page tab skeleton, named dashboards, routing, and the Users→Authentik + Observability-split decisions.

• 11.3 Update CHANGELOG.md

---

Slice 12 — Verify

• 12.1 Cross-route manual pass

  • Details: Walk every service type's page + tabs; walk named dashboards; walk the empty state; confirm legacy routes 404.

• 12.2 Verify report

  • Files: openspec/changes/services-as-hub-ia/verify-report.md
  • Details: Per-AC evidence (AC1–AC10), tool versions, manual notes, residual risks.

---

Notes

• Slices 1–3 are backend-only; slice 4 is the frontend shell turning on the new IA with stubs; 5–9 replace stubs with real content; 10 adds named dashboards; 11–12 close out.
• Slices 5–9 are independent and can be reordered or parallelized across branches if useful, but each must merge green with its stub replaced.
• The frontend content lifts (5–9) are the bulk of the line count; treat each as a self-contained review-sized PR.