manage/openspec/changes/configurable-dashboard-widgets/specs/dashboard-widgets/spec.md

Dashboard Widgets Specification

Domain: dashboard-widgets · Change: configurable-dashboard-widgets Full spec (no prior canonical spec exists for this domain).

Purpose

Define WHAT must be true after Phase 1 of the configurable dashboard widgets change: the Manage dashboard becomes a persisted, configurable stack of widget instances backed by a closed, compile-time registry. Authenticated users can add, edit, enable/disable, reorder, and remove widgets; widget data is fetched independently; misconfigured widgets fail gracefully; and addon pages render under /addons/{addon_id}.

Scope Summary

In scope

• Closed compile-time widget/source registries in the backend and frontend.
• SQLite persistence of widget instances (dashboard_widgets table).
• Source adapters for jellyfin, backups, grafana, prometheus, and ssh_task, plus a static text/markdown widget.
• REST API for widget instance CRUD and per-instance data fetch.
• Dashboard rendering loop in Dashboard.tsx using widget instances.
• Configuration UI for add/edit/reorder/remove widgets.
• Addon page route /addons/:addonId with a static addon page registry.
• Default widget seeding on first install.

Out of scope (reminders)

• Runtime addon discovery or dynamic component loading.
• Per-user widget configuration.
• Grid, drag, or resize layout engine.
• Iframe embedding of Grafana or any external UI.
• Public/unauthenticated widget access.
• Generic "run any script" widget; only saved tasks from the existing registry are allowed.
• Real-time WebSocket updates.

Requirements

Requirement: Widget instance persistence

The backend MUST persist widget instances in a dashboard_widgets table with the following columns and invariants:

• id TEXT PRIMARY KEY
• addon_id TEXT NOT NULL
• widget_type TEXT NOT NULL
• title TEXT NOT NULL
• config_json TEXT NOT NULL (source-specific JSON config)
• enabled INTEGER NOT NULL DEFAULT 1
• sort_order INTEGER NOT NULL DEFAULT 0
• created_at INTEGER NOT NULL
• updated_at INTEGER NOT NULL

The table MUST have an index on sort_order named idx_dashboard_widgets_sort.

The SettingsStore MUST provide CRUD helpers that return plain Python dicts matching the API response shape. config_json MUST be stored as JSON text and validated on write.

Scenario: Create and read a widget instance

• GIVEN an empty dashboard_widgets table
• WHEN the store creates a widget instance with addon_id="core", widget_type="static", title="Notes", config_json={"text":"hello"}, enabled=true, sort_order=1
• THEN list_widgets() returns a list containing one item with the same field values
• AND created_at and updated_at are Unix epoch seconds

Scenario: Update enabled and sort_order

• GIVEN an existing widget instance
• WHEN the store updates enabled to false and sort_order to 5
• THEN subsequent reads reflect the new values
• AND updated_at is greater than or equal to the write time

Scenario: Delete a widget instance

• GIVEN an existing widget instance
• WHEN the store deletes it by id
• THEN list_widgets() no longer returns that instance

---

Requirement: Default widget seeding on first install

On first install (when dashboard_widgets is empty during startup or ensure_defaults), the system MUST seed exactly two default widget instances:

1. addon_id="core", widget_type="jellyfin", title="Jellyfin activity", enabled, sort_order before backups.
2. addon_id="backups", widget_type="backups", title="Backups", enabled, sort_order after Jellyfin.

Existing installations with one or more widget rows MUST NOT be modified by the seeding logic.

Scenario: Fresh install shows default widgets

• GIVEN a fresh settings database with no dashboard_widgets rows
• WHEN the backend starts or ensure_defaults() runs
• THEN GET /api/widgets/instances returns exactly the Jellyfin activity and Backups widgets in that order
• AND both are enabled

Scenario: Existing install is not re-seeded

• GIVEN a settings database with at least one dashboard_widgets row
• WHEN the backend starts
• THEN the existing widget rows remain unchanged
• AND no new default rows are inserted

---

Requirement: Closed widget and source registries

The widget system MUST use a closed, compile-time registry. The backend MUST reject any widget_type not in the registry and any source_type without a registered adapter.

Phase 1 built-in widget types:

widget_type	addon_id	Source adapter	Purpose
jellyfin	core	jellyfin	Activity/counts from a Jellyfin machine
backups	backups	backups	Backup summary stats
grafana-link	grafana	grafana	Deep-link to a Grafana dashboard or panel
prometheus-metric	prometheus	prometheus	Instant query rendered as a metric
ssh-task	ssh-tasks	ssh_task	Output of a saved task
static	core	static	Plain text/markdown widget

Scenario: Unknown widget type is rejected

• GIVEN a POST /api/widgets/instances request with widget_type="unknown"
• WHEN the request is processed
• THEN the response status is 422 Unprocessable Entity
• AND the response body contains a validation error naming the unsupported widget type

Scenario: Source registry is fixed

• GIVEN GET /api/widgets/sources
• WHEN the endpoint responds
• THEN the list contains exactly jellyfin, backups, grafana, prometheus, ssh_task, and static

---

Requirement: Widget config validation

Each widget type MUST have a JSON config schema. The backend MUST validate config_json against the schema on create and update and reject credential fields.

The following keys are forbidden anywhere in config_json (case-insensitive):

• password, token, secret, api_key, apikey, private_key, passphrase, credential

Any value that is a non-empty string and looks like a secret (e.g., starts with sk-, eyJ, or is longer than 64 random-looking characters) SHOULD be rejected as a defense-in-depth measure.

Scenario: Valid static widget config passes

• GIVEN a POST /api/widgets/instances request with widget_type="static" and config_json={"text":"Hello"}
• WHEN the request is processed
• THEN the response status is 200 OK or 201 Created
• AND the stored config_json equals the submitted value

Scenario: Credential field in config is rejected

• GIVEN a POST /api/widgets/instances request with config_json={"api_key":"abc123"}
• WHEN the request is processed
• THEN the response status is 422 Unprocessable Entity
• AND the error message indicates that credential fields are not allowed

Scenario: Jellyfin config requires machine_id

• GIVEN a POST for widget_type="jellyfin" with config_json={}
• WHEN the request is processed
• THEN the response status is 422 Unprocessable Entity
• AND the error indicates that machine_id is required

---

Requirement: Widget source adapters

Each source adapter MUST implement a uniform async interface:

class WidgetSource(Protocol):
    source_type: str
    async def fetch(self, config: dict[str, Any]) -> dict[str, Any]: ...

Adapters MUST reuse existing dependency-injection helpers and MUST NOT reimplement client logic:

• jellyfin: get_jellyfin_client + existing client.sessions() / counts.
• backups: BackupDashboardSummary building logic from dashboard.py.
• grafana: get_settings() Grafana URL; only returns deep-link metadata, never embeds.
• prometheus: get_settings() Prometheus URL; performs an instant query via HTTP.
• ssh_task: existing saved task registry + run_task helper.
• static: returns the text/markdown from config_json unchanged.

Adapters MUST catch their own exceptions and return an error payload; they MUST NOT raise unhandled exceptions into the endpoint.

Scenario: Jellyfin adapter returns sessions

• GIVEN a Jellyfin widget configured with a valid machine_id
• WHEN GET /api/widgets/instances/{id}/data is called
• THEN the response contains a data field with activity rows
• AND error is null

Scenario: SSH task adapter times out gracefully

• GIVEN an ssh-task widget configured with a slow task
• WHEN the adapter exceeds its timeout
• THEN it returns { "error": "Widget data fetch timed out" }
• AND the HTTP endpoint still responds with 200 OK carrying the error payload

---

Requirement: API contract

The backend MUST expose the following endpoints under /api/widgets, protected by the existing JWT/API-key auth:

Method	Path	Purpose	Success	Error
GET	/api/widgets/sources	List source types	200 OK + list of strings	401/403
GET	/api/widgets/types	List widget types per addon	200 OK + WidgetTypeInfo[]	401/403
GET	/api/widgets/instances	List persisted instances	200 OK + WidgetInstance[]	401/403
POST	/api/widgets/instances	Create instance	201 Created + WidgetInstance	400/401/403/422
PUT	/api/widgets/instances/{id}	Update instance	200 OK + WidgetInstance	400/401/403/404/422
DELETE	/api/widgets/instances/{id}	Delete instance	200 OK + {status:"deleted"}	401/403/404
GET	/api/widgets/instances/{id}/data	Fetch widget data	200 OK + WidgetDataResponse	401/403/404/500

WidgetInstance response fields (exact names):

• id: string
• addon_id: string
• widget_type: string
• title: string
• config: object (parsed JSON)
• enabled: boolean
• sort_order: number
• created_at: number
• updated_at: number

WidgetInstanceInput request fields:

• id: string | null (optional on create)
• addon_id: string
• widget_type: string
• title: string
• config: object
• enabled: boolean
• sort_order: number

WidgetTypeInfo fields:

• addon_id: string
• widget_type: string
• name: string
• description: string
• source_type: string
• config_schema: JSON Schema object

WidgetDataResponse fields:

• widget_id: string
• widget_type: string
• data: object | null
• error: string | null
• fetched_at: number (Unix epoch seconds)

Scenario: Create widget instance via API

• GIVEN an authenticated POST /api/widgets/instances with a valid WidgetInstanceInput
• WHEN the request is processed
• THEN the response status is 201 Created
• AND the response body contains the created WidgetInstance with a generated id

Scenario: Update nonexistent widget returns 404

• GIVEN an authenticated PUT /api/widgets/instances/does-not-exist
• WHEN the request is processed
• THEN the response status is 404 Not Found

Scenario: Data endpoint returns error for misconfigured widget

• GIVEN a widget whose adapter returns an error payload
• WHEN GET /api/widgets/instances/{id}/data is called
• THEN the response status is 200 OK
• AND error is a non-empty string
• AND data is null

---

Requirement: Type contracts

The Pydantic models in the backend and the TypeScript interfaces in the frontend MUST use the exact field names listed above.

Backend Pydantic models MUST live in backend/src/media_library_viewer_api/models/widgets.py and MUST include:

• WidgetInstance
• WidgetInstanceInput
• WidgetTypeInfo
• WidgetDataResponse

Frontend TypeScript interfaces MUST be added to frontend/src/types/index.ts:

• WidgetInstance
• WidgetInstanceInput
• WidgetTypeInfo
• WidgetDataResponse
• WidgetSource (string union of source types)

Scenario: Backend model serializes config as object

• GIVEN a WidgetInstance model initialized from a database row with config_json='{"text":"x"}'
• WHEN it is serialized with model_dump()
• THEN config is the parsed object {"text":"x"}

Scenario: Frontend type matches API response

• GIVEN the WidgetInstance TypeScript interface
• WHEN a widget instance payload from GET /api/widgets/instances is typed with it
• THEN npm run build succeeds without type errors

---

Requirement: Dashboard rendering loop

frontend/src/pages/Dashboard.tsx MUST render widget instances returned by useWidgetInstances() instead of the three hard-coded sections.

The dashboard MUST:

• Query widget instances on mount.
• Render only instances with enabled === true.
• Sort enabled instances by sort_order ascending.
• Render each widget inside the existing SectionCard container.
• Pass the widget instance to a registered widget component.
• Preserve the existing stacked layout (flex flex-col gap-4).
• Keep the existing Shortcuts functionality as a widget type or continue to support it as a first-class widget instance (widget_type="shortcuts" or equivalent) so that no data is lost.

Scenario: Fresh install rendering

• GIVEN a fresh install with default widgets
• WHEN the Dashboard page loads
• THEN it renders the Jellyfin activity widget followed by the Backups widget
• AND both fetch their own data independently

Scenario: Disabled widget is hidden

• GIVEN a widget instance with enabled=false
• WHEN the Dashboard renders
• THEN that widget is not rendered
• AND the remaining widgets maintain their sort order

Scenario: Misconfigured widget fails gracefully

• GIVEN a dashboard with one valid widget and one widget whose data endpoint returns an error
• WHEN the Dashboard renders
• THEN the valid widget displays normally
• AND the failing widget renders an inline Alert with the error message
• AND the rest of the dashboard is not blocked

---

Requirement: Independent widget data fetching

Each widget MUST fetch its own data independently via useWidgetData(widgetId, refreshInterval). The hook MUST use TanStack Query with a per-widget refetchInterval.

Default refresh intervals:

• jellyfin: 30 seconds
• backups: 60 seconds
• grafana: 0 (no polling; static link)
• prometheus: 30 seconds
• ssh_task: 0 (fetch on mount only; heavy)
• static: 0

A widget component MUST show a loading state while data is being fetched for the first time and MUST show an error state if error is non-null.

Scenario: Jellyfin widget auto-refreshes

• GIVEN a rendered Jellyfin widget
• WHEN 30 seconds elapse
• THEN useWidgetData refetches the data automatically

Scenario: Grafana widget does not poll

• GIVEN a rendered Grafana-link widget
• WHEN it mounts
• THEN it fetches data once to build the deep-link
• AND it does not refetch automatically

---

Requirement: Configuration UI

The Dashboard MUST provide an "Edit dashboard" action that opens a configuration panel or dialog. The panel MUST allow the user to:

• See all widget instances (enabled and disabled).
• Add a new widget by choosing a widget type from the closed registry.
• Edit a widget's title, enabled flag, sort_order, and source-specific config.
• Remove a widget with a confirmation step.
• Reorder widgets by changing sort_order (simple numeric input or up/down buttons).

Source-specific config fields MUST be rendered by small sub-forms registered next to each widget type in the frontend registry.

The UI MUST reuse existing shadcn/ui form patterns (Dialog, Input, Label, Switch, Select, Button, Alert).

Scenario: User adds a Grafana-link widget

• GIVEN the dashboard configuration panel is open
• WHEN the user selects widget type grafana-link, enters title="Grafana Overview", config.dashboard_uid="overview", and saves
• THEN a new widget instance is persisted
• AND it appears on the dashboard with a deep-link to Grafana

Scenario: User disables a widget

• GIVEN the dashboard configuration panel is open and a widget is enabled
• WHEN the user toggles its enabled switch off and saves
• THEN the widget disappears from the dashboard
• AND it remains in the instances list with enabled=false

Scenario: Reorder widgets

• GIVEN two widgets with sort_order 0 and 1
• WHEN the user swaps their sort_order values and saves
• THEN the dashboard re-renders them in the new order

---

Requirement: Addon pages

The frontend MUST register a route /addons/:addonId in App.tsx. The AddonPage component MUST look up addonId in a static addon registry and render the matching page component.

Phase 1 addon registry MUST include at least:

• grafana — GrafanaAddonPage
• prometheus — PrometheusAddonPage
• ssh-tasks — SshTasksAddonPage

Navigating to an unknown addonId MUST render a 404-style message inside the page shell.

Grafana widgets MUST deep-link to Grafana (using env-configured URL) instead of embedding.

Scenario: Addon page navigation

• GIVEN the user clicks "Open Grafana addon" from a Grafana widget
• WHEN the browser navigates to /addons/grafana
• THEN the GrafanaAddonPage component renders
• AND the page shows Grafana deep-links and no iframe

Scenario: Unknown addon page

• GIVEN a navigation to /addons/unknown
• WHEN the route resolves
• THEN the page renders an Alert stating the addon is not found
• AND the sidebar and shell remain intact

---

Non-Functional Requirements

Requirement: Security — no secrets in widget config

The system MUST ensure that widget config_json never stores secrets. Credential detection MUST be applied both at the Pydantic model level and at the store write level. Backend adapters MUST resolve credentials from the existing machine/SSH-key store or environment settings.

Scenario: Secret-looking value rejected

• GIVEN a widget config containing "token": "super-secret-api-token-value"
• WHEN the create/update endpoint processes it
• THEN the request is rejected with 422 Unprocessable Entity

---

Requirement: Performance — independent fetches and timeouts

Each widget data fetch MUST be independent. A slow or failing adapter MUST NOT block other widgets or the dashboard render. Adapters MUST apply a short timeout:

• jellyfin: 10 seconds
• backups: 10 seconds
• prometheus: 10 seconds
• ssh_task: 30 seconds
• grafana: 5 seconds
• static: no fetch

The dashboard MUST render the widget chrome immediately and show loading skeletons while data loads.

Scenario: Slow widget does not block dashboard

• GIVEN a dashboard with three widgets, one of which takes 25 seconds
• WHEN the dashboard loads
• THEN the other two widgets render their data immediately
• AND the slow widget shows a loading skeleton until it completes or times out

---

Requirement: Maintainability — closed registry

The widget and source registries MUST be closed and compile-time. Adding a new widget type or source adapter MUST require a code change in both backend and frontend registries. There MUST be no plugin loading, dynamic imports, or runtime manifests in Phase 1.

Scenario: Registry is discoverable in source

• GIVEN the source code
• WHEN searching for the list of supported widget types
• THEN it is found as an explicit map/list in the backend and frontend source files

---

Invariants and Validation Rules

1. widget_type MUST be in the closed registry.
2. addon_id MUST match the addon registered for the widget type.
3. config_json MUST be valid JSON and MUST validate against the widget type's JSON schema.
4. config_json MUST NOT contain keys matching the forbidden credential list.
5. sort_order MUST be a non-negative integer.
6. enabled MUST be a boolean.
7. The data endpoint for a disabled widget MUST still function if called directly, but the dashboard MUST NOT render it.
8. A widget instance's id MUST be immutable after creation.
9. Source adapters MUST be stateless and MUST NOT persist widget-specific secrets.
10. Addon page components MUST NOT embed external iframes.

Error Handling Requirements

Flow / Endpoint	Expected Error Condition	Response
GET /api/widgets/instances	Unauthenticated	401 Unauthorized
POST /api/widgets/instances	Invalid JSON	400 Bad Request
POST /api/widgets/instances	Unknown widget_type	422 Unprocessable Entity
POST /api/widgets/instances	Config fails schema validation	422 Unprocessable Entity
POST /api/widgets/instances	Config contains credential key	422 Unprocessable Entity
PUT /api/widgets/instances/{id}	Widget not found	404 Not Found
PUT /api/widgets/instances/{id}	ID in path mismatches body	400 Bad Request
DELETE /api/widgets/instances/{id}	Widget not found	404 Not Found
GET /api/widgets/instances/{id}/data	Widget not found	404 Not Found
GET /api/widgets/instances/{id}/data	Adapter raises unhandled exception	500 Internal Server Error with a safe message
GET /api/widgets/instances/{id}/data	Adapter returns error payload	200 OK with error set
Dashboard render	Widget data hook errors	Inline error state; dashboard continues
Configuration UI	Network error on save	Inline Alert; form remains open

Scenario Catalog

Scenario: Fresh install shows default widgets

• GIVEN a fresh settings database
• WHEN the backend starts and the Dashboard page loads
• THEN GET /api/widgets/instances returns two enabled widgets: Jellyfin activity and Backups
• AND the Dashboard renders them in order

Scenario: User adds a Grafana-link widget

• GIVEN the Dashboard configuration panel is open
• WHEN the user chooses grafana-link, sets title="Grafana Overview", config.dashboard_uid="overview", and saves
• THEN POST /api/widgets/instances succeeds
• AND the new widget appears on the dashboard
• AND clicking the widget opens the Grafana dashboard in a new tab

Scenario: User disables a widget

• GIVEN a widget is enabled and visible on the dashboard
• WHEN the user opens the configuration panel, toggles the widget off, and saves
• THEN PUT /api/widgets/instances/{id} returns enabled=false
• AND the widget is no longer rendered on the dashboard

Scenario: Misconfigured widget fails gracefully

• GIVEN a prometheus-metric widget with an invalid promql query
• WHEN the dashboard renders
• THEN the widget shows an error Alert with a message from the adapter
• AND all other widgets render normally
• AND the dashboard remains scrollable and interactive

Scenario: Addon page navigation

• GIVEN a Grafana widget with a configured dashboard
• WHEN the user clicks the addon deep-link
• THEN the browser navigates to /addons/grafana
• AND the GrafanaAddonPage renders with relevant deep-links
• AND no iframe is present

File Targets (Informative)

• Backend models: backend/src/media_library_viewer_api/models/widgets.py
• Backend router: backend/src/media_library_viewer_api/routers/widgets.py
• Backend source adapters: backend/src/media_library_viewer_api/widgets/*.py
• Backend store: extend backend/src/media_library_viewer_api/services/settings_store.py
• Backend main: register router in backend/src/media_library_viewer_api/main.py
• Frontend types: frontend/src/types/index.ts
• Frontend API client: frontend/src/api/widgets.ts
• Frontend hooks: frontend/src/hooks/useWidgets.ts
• Frontend widget registry: frontend/src/widgets/registry.ts
• Frontend widget components: frontend/src/widgets/*.tsx
• Frontend dashboard: frontend/src/pages/Dashboard.tsx
• Frontend addon page: frontend/src/pages/AddonPage.tsx
• Frontend app routes: frontend/src/App.tsx