manage/openspec/changes/configurable-dashboard-widgets/apply-progress.md

# Apply Progress: Configurable Dashboard Widgets

**Change:** `configurable-dashboard-widgets`  
**Apply run:** PR 1 / Slice 1 — Backend CRUD and default seeding  
**Date:** 2026-06-19

## Completed tasks (Slice 1)

All Slice 1 tasks are marked `- [x]` in `tasks.md`:

- [x] 1.1 Create widget Pydantic models
- [x] 1.2 Create backend widget registry
- [x] 1.3 Implement widgets router (CRUD + metadata)
- [x] 1.4 Extend `SettingsStore` for `dashboard_widgets`
- [x] 1.5 Register widgets router in `main.py`
- [x] 1.6 Add backend tests for registry, CRUD, and seeding
- [x] 1.7 Verify backend slice

## Files changed

### New files

- `backend/src/media_library_viewer_api/models/widgets.py` — Pydantic models: `WidgetInstance`, `WidgetInstanceInput`, `WidgetTypeInfo`, `WidgetDataResponse`, plus credential-key/secret-value validators.
- `backend/src/media_library_viewer_api/widgets/__init__.py` — Package marker.
- `backend/src/media_library_viewer_api/widgets/registry.py` — Closed `WIDGET_REGISTRY` for six Phase 1 widget types, source-type listing, type metadata, and lightweight config-schema validation.
- `backend/src/media_library_viewer_api/routers/widgets.py` — REST endpoints for `/api/widgets/sources`, `/types`, `/instances`, and instance CRUD.
- `backend/tests/test_widgets.py` — 12 tests covering registry, CRUD, validation, and seeding.

### Modified files

- `backend/src/media_library_viewer_api/services/settings_store.py` — Added `dashboard_widgets` table, index, CRUD helpers, default seeding, and refactored `ensure_defaults()` to seed widgets independently of machine seeding.
- `backend/src/media_library_viewer_api/main.py` — Registered `widgets_router`.

## Verification

Commands run:

```bash
cd backend
.venv/bin/python -m ruff check .              # All checks passed
PYTHONPATH=src .venv/bin/python -m pytest     # 185 passed, 2 warnings
cd ../frontend
npm run lint                                  # 2 pre-existing warnings, 0 errors
npm run build                                 # Built successfully
```

Focused widget test output: `12 passed`.

## Deviations from design

- None significant for Slice 1. The implementation follows the design's backend CRUD layout.
- Used `HTTP_422_UNPROCESSABLE_CONTENT` instead of the deprecated `HTTP_422_UNPROCESSABLE_ENTITY`.

## Completed tasks (Slice 2)

All Slice 2 tasks are marked `- [x]` in `tasks.md`:

- [x] 2.1 Add observability URL settings (`grafana_url`, `prometheus_url`)
- [x] 2.2 Create source adapters (`jellyfin`, `backups`, `grafana`, `prometheus`, `ssh_task`, `static`)
- [x] 2.3 Add per-widget data endpoint (`GET /api/widgets/instances/{id}/data`)
- [x] 2.4 Extract shared backup/Jellyfin dashboard helpers into `domain/dashboard.py`
- [x] 2.5 Add adapter + data endpoint tests

## Files changed (Slice 2)

### New files

- `backend/src/media_library_viewer_api/widgets/sources.py` — `WidgetSource` protocol and six source adapters.
- `backend/src/media_library_viewer_api/domain/dashboard.py` — Shared dashboard helpers (`_map_sessions_to_activity_rows`, `build_backup_dashboard_summary`).

### Modified files

- `backend/src/media_library_viewer_api/config.py` — Added `grafana_url` and `prometheus_url` settings.
- `backend/src/media_library_viewer_api/routers/widgets.py` — Added `GET /api/widgets/instances/{id}/data`.
- `backend/src/media_library_viewer_api/routers/dashboard.py` — Delegated to shared `domain/dashboard.py` helpers.
- `backend/tests/test_widgets.py` — Added adapter and data endpoint tests.
- `docker-compose.yml`, `docker-compose.dev.yml`, `.env.example` — Wired `GRAFANA_URL` and `PROMETHEUS_URL` for the new adapters.

## Verification (Slice 2)

```bash
cd backend
.venv/bin/python -m ruff check .              # All checks passed
PYTHONPATH=src .venv/bin/python -m pytest     # 200 passed, 2 warnings
cd ../frontend
npm run lint                                  # 2 pre-existing warnings, 0 errors
npm run build                                 # Built successfully
```

Focused widget test output: `27 passed`.

## Deviations from design (Slice 2)

- Adapters currently call `get_settings_store()` internally for `backups`/`ssh_task` sources. The router-level endpoint uses FastAPI DI, but adapter unit tests patch `get_settings_store` to inject a test store. A future refactor can pass `store` and `settings` explicitly into `adapter.fetch()` for cleaner testability.

## Completed tasks (Slice 3)

All Slice 3 tasks are marked `- [x]` in `tasks.md`:

- [x] 3.1 Add TypeScript widget interfaces (`WidgetInstance`, `WidgetInstanceInput`, `WidgetTypeInfo`, `WidgetDataResponse`)
- [x] 3.2 Create widget API client (`frontend/src/api/widgets.ts`)
- [x] 3.3 Create widget TanStack Query hooks (`frontend/src/hooks/useWidgets.ts`)
- [x] 3.4 Create frontend widget registry (`frontend/src/widgets/registry.ts`)
- [x] 3.5 Implement six widget presentational components (`frontend/src/widgets/*.tsx`)
- [x] 3.6 Add frontend registry unit test (`frontend/src/widgets/registry.test.ts`)

## Files changed (Slice 3)

### New files

- `frontend/src/api/widgets.ts` — API functions for widget CRUD, registry metadata, and per-widget data.
- `frontend/src/hooks/useWidgets.ts` — TanStack Query hooks for instances, data, sources, types, and mutations.
- `frontend/src/widgets/registry.ts` — Closed frontend registry with metadata, refresh intervals, and config fields.
- `frontend/src/widgets/JellyfinWidget.tsx` — Renders Jellyfin session activity.
- `frontend/src/widgets/BackupsWidget.tsx` — Renders backup dashboard summary.
- `frontend/src/widgets/GrafanaLinkWidget.tsx` — Renders a deep-link to Grafana (no iframe).
- `frontend/src/widgets/PrometheusMetricWidget.tsx` — Renders PromQL instant query result.
- `frontend/src/widgets/SshTaskWidget.tsx` — Renders saved SSH task output.
- `frontend/src/widgets/StaticWidget.tsx` — Renders static text.
- `frontend/src/widgets/index.ts` — Barrel exports.
- `frontend/src/widgets/registry.test.ts` — Vitest unit tests for registry metadata.

### Modified files

- `frontend/src/types/index.ts` — Added widget TypeScript interfaces.

## Verification (Slice 3)

```bash
cd backend
.venv/bin/python -m ruff check .              # All checks passed
PYTHONPATH=src .venv/bin/python -m pytest     # 200 passed, 2 warnings
cd ../frontend
npm run lint                                  # 2 pre-existing warnings, 0 errors
npm run build                                 # Built successfully
npm run test -- src/widgets/registry.test.ts  # 3 passed
```

## Deviations from design (Slice 3)

- Registry unit test is colocated at `frontend/src/widgets/registry.test.ts` and runs with Vitest, matching the project's existing `npm run test` setup, instead of `frontend/tests/widgets.test.mjs`.
- `JellyfinWidget` uses `SessionActivityPanel` directly because `NowPlaying` does not expose an `emptyMessage` prop.

## Remaining work

- Slice 4: Dashboard loop + configuration UI + addon pages

## PR boundary

This slice is **PR 1 of 4** in the approved stacked-to-main chain. It is backend-only and leaves the frontend build/lint green.

**Actual changed-line count:** ~780 added lines across production code and tests (new files: ~597 lines; modified files: ~181 insertions). This is above the nominal ~400-line review budget, but Slice 1 is the smallest coherent backend unit: removing the CRUD router, store helpers, or tests would leave the slice non-functional or unverifiable. If the reviewer prefers a smaller blast radius, the store helpers (~90 lines) could be split into a preceding PR, though that PR would not be independently user-visible.