Developer
caf6c226ff
The IA shell lands. The static navItems array is replaced by useNavItems(),
which combines useServiceInstances (enabled instances) + useDashboards to
build the nav in spec order: Main Dashboard, named dashboards, conditional
service-type entries (one per configured type; ssh_tasks contributes Files
+ Actions, nextcloud contributes none), Services, Settings.
Legacy top-level routes (/media, /files, /actions, /users, /observability,
/backups, /monitoring, /applications) are removed; a NotFoundPage catch-all
returns 404 (R4.7).
ServicePage is refactored to a tab skeleton: Overview | type-specific
content tabs | Widgets | Config. serviceContentTabs(type) returns the
per-type set (jellyfin=Media+Requests, ssh_tasks=Files+Actions, backups=Jobs,
authentik=Users+Messaging, alertmanager=Alerts, grafana=Links,
prometheus=Metrics, nextcloud=none). Content tabs are stubs ('coming soon');
real content migrates in slices 5-9. Widgets + Config tabs preserve the
existing widget-list and config/secrets editing verbatim.
ServiceTypePage resolves /services/:type (no id) by redirecting to the
first enabled instance; empty state when none.
Instance switcher (Select) appears when >1 ENABLED sibling of the same
type exists (R3.1).
Empty states: Dashboard shows an 'Add a service' CTA when no instances
exist; ServicesPage already had a strong empty state.
Fixes from Slice 4 review:
- B1 (blocker): secret editing regressed because buildInput() hardcoded
secrets:{} after the ConfigBody lift orphaned draftSecrets. Lifted
draftSecrets to the parent ServicePage; buildInput now sends only the
non-blank typed drafts ('leave blank to keep' semantics restored).
- S1: switcher trigger keys off enabled siblings, not total.
New: navEntries.ts + test, dashboards api/hook, service-tabs/ stubs +
index, ServiceTypePage, ServicePage tab skeleton + ConfigBody lift,
Dashboard empty-state CTA, ServicePage tab/switcher/secret-save tests.
Note: this branch is based on main (mobile-responsive-parity is unmerged);
the mobile SheetForm on ServicePage will be re-added when content tabs
get real content (slices 5-9). 84 tests pass (+1 secret-save guard);
lint/build green.
Refs openspec/changes/services-as-hub-ia/ (spec R1-R4/R9, tasks slice 4).
Manage Frontend
React + TypeScript SPA for Manage, consuming the FastAPI backend.
Tech Stack
- Vite — Build tool
- React 18+ — UI framework
- TypeScript — Type safety
- @tanstack/react-query — Data fetching/caching
- @tanstack/react-table — Data tables (media, file browser)
- react-router-dom — Client-side routing
- Tailwind CSS + shadcn/ui — Styling
Setup
cd frontend
npm install
Development
npm run dev
Runs on http://localhost:5173 with API requests proxied to http://localhost:8000.
Make sure the backend is running:
cd ../backend
uvicorn media_library_viewer_api.main:app --reload --port 8000
Build
npm run build
Output goes to frontend/dist/.
Pages
- Dashboard (
/) — Now playing, library stats, configurable widgets and shortcuts, frontend/backend version chips in the shell header - Observability (
/observability) — Thin dashboard: Alertmanager alerts, Prometheus target health, machine status, and Grafana deep-links (no in-app charting) - Media (
/media) — Full-library table with sort/filter/search - Users (
/users) — Read-only Jellyfin user list with optional Jellyseerr enrichment - File Browser (
/files) — Remote directory browsing, ffprobe preview, jobs - Settings (
/settings) — Persistent monitoring machine definitions, SSH keys, and setup workflow - Actions (
/actions) — Saved server tasks (shell/python) targeting ssh_tasks services
Environment Variables
Set VITE_API_URL and any OIDC variables directly in your shell or Compose build args if the API is not at http://localhost:8000.
The frontend version defaults to the package.json version and can be overridden with VITE_APP_VERSION and VITE_APP_BUILD_INFO when you need explicit deployed labels.
VITE_API_URL=http://your-backend-host:8000
Configuration workflow examples
- Local development: run
docker compose -f docker-compose.dev.yml up --build, then open the app and add monitoring machines in the Settings tab. - Production: export the required Compose variables in your shell, run
docker compose up --build, and manage local/remote machines from Settings. - Observability: Manage only deploys backend + frontend. It connects to existing Grafana/Prometheus/Alertmanager instances; see
docker-compose.observability.ymlfor an optional standalone example stack. A machine can belocal(the API host itself) orssh(a remote host), and the UI treats both the same after configuration.
In development, the Vite proxy handles /api requests automatically. Observability services (Grafana, Prometheus, Alertmanager) are configured in the app on the Services page — there are no observability env vars.