--- path: /studio/isis/resource-recommendations surface: studio domain: isis auth: signed-in + studio entitlement boundary; admin-scoped BFF data; direct legacy route hard-blocked outside the localhost E2E lane bypass source: apps/oshun/web/src/app/studio/isis/resource-recommendations/page.tsx status: walked last_walked: '2026-07-01 real-dev-infra Playwright journey — direct route hard-block, localhost lane-bypass admin session, live BFF GET/POST forwarding, downgrade/no-downgrade recommendations, fail-closed malformed states, route map, quick actions, touch targets, non-admin unauthorized, and anonymous redirect. Evidence: WALKTHROUGH/results/v1-real-infra-run-2026-06-22.md#260-2026-07-01-studio-isis-resource-recommendations-coverage' --- # Isis Resource Recommendations ## Purpose Admin lane console that trades a known quality drop for a known spend reduction. Given a current model and a fallback reason, the engine walks the priority-ordered model chain to the next cheaper model and reports the exact cost-savings and quality-impact percentages of the downgrade. ## Entry points - Embedded as the "Resource Recommendations Lane" inside `/studio/isis/gpu-worker`, `/studio/isis/generation-api` - Studio index (`/studio`) - Direct URL / bookmark ## Layout regions `page.tsx` mounts `ShellLayout active="studio"` and three panels (no breadcrumb panel). - **Workspace panel** (`data-isis-resource-recommendations-workspace`): - `

` "Isis Resource Recommendations Workspace" (`WorkspaceHeading`) - Summary paragraph (`data-recommend-summary`) - Fallback chain (`data-recommend-chain`, `

`) of priority-ordered `data-recommend-chain-entry` cards - The "Request a downgrade recommendation" form (`data-recommend-form`) - Recommendation list (`data-recommend-list`, `

`) of `data-recommend-record` cards carrying `data-recommend-has-downgrade` - **Route map panel** (`data-isis-resource-recommendations-route-map`): `

` "Route Map" enumerating `STUDIO_ISIS_RESOURCE_RECOMMENDATIONS_ROUTE_MAP` - **Quick-actions panel**: `quickAction` links to `/studio/isis/content-safety` and "Back to Studio workspace index" → `/studio` ## States - [x] **Loading** — `data-recommend-loading` "Loading recommendations…" - [x] **Unauthorized** — `data-recommend-unauthorized` (admin-scope fail-closed on 401/403) - [x] **Error** — `data-recommend-error` on non-OK / malformed response - [x] **Ready (form)** — chain + form + recommendation list render; empty list shows `data-recommend-list-empty` - [x] **Result** — `data-recommend-result` with `data-recommend-status` (`ok` / `error`) ## Interactions ### Request a downgrade recommendation (`data-recommend-form`) - [x] **Recommendation id** — `data-recommend-id` text input - [x] **Current model** — `data-recommend-model` select (options from the response `chain`) - [x] **Reason** — `data-recommend-reason` select (options from the response `reasons`) - [x] **Recommend downgrade** — `data-recommend-run` submit; POSTs to `/v1/admin/isis/resource-recommendations`, then reloads the list ### Route map - [x] **Route-map articles** — non-interactive path + purpose entries ### Quick-actions - [x] **Open Isis Content Safety workspace** → `/studio/isis/content-safety` - [x] **Back to Studio workspace index** → `/studio` ## Data & contracts - **Reads**: `GET /v1/admin/isis/resource-recommendations` (`RECOMMENDATION_ENDPOINT`) on mount — fallback chain + reasons + recommendations - **Writes**: `POST /v1/admin/isis/resource-recommendations` — compute a downgrade recommendation - **Validation**: client requires a non-empty generated timestamp, non-empty valid chain/reason catalogs, non-negative finite chain/recommendation numerics, downgrade target/reason membership in the catalog, and `recommendedAtUnixSeconds` on every recommendation before rendering or acknowledging a write - **Realtime**: None - **Caching**: client `fetch` on mount, `cache: 'no-store'`, `buildBffAuthHeaders()` - **Auth**: direct legacy Studio route is hard-blocked by the Studio boundary; the localhost-only E2E lane bypass exercises the signed-in Studio shell and forwards admin-scoped BFF calls fail-closed (401/403 → unauthorized state) - **Component sources**: - `apps/oshun/web/src/components/studio/StudioIsisResourceRecommendationsWorkspace.tsx` - `apps/oshun/web/src/components/studio/StudioIsisResourceRecommendationsRouteMap.ts` ## Automated coverage - `apps/oshun/web/e2e/studio-isis-resource-recommendations.spec.ts` covers the direct-route hard block, localhost lane-bypass admin session, live BFF fallback catalog, seeded recommendations, valid downgrade and cheapest-model no-downgrade POSTs, duplicate/off-chain rejection, client validation, pending-submit disablement, malformed catalog/record fail-closed handling, route-map articles, quick-actions, 44px form/link hit targets, non-admin unauthorized, anonymous redirect, and the shared axe gate. - `apps/oshun/web/src/components/__tests__/StudioIsisResourceRecommendationsWorkspace.test.tsx` covers ready/unauthorized/malformed list behavior. - `apps/oshun/web/src/components/__tests__/StudioIsisResourceRecommendationsWorkspace.integration.test.tsx` covers write success, reload, pending state, and malformed successful write handling. - `apps/oshun/web/src/components/__tests__/StudioIsisResourceRecommendationsPage.test.tsx` and `StudioIsisResourceRecommendationsRouteMap.test.ts` keep the shell/page contract and route-map content covered. ## Cross-references - Studio overview: [`../../studio-overview.md`](../../studio-overview.md) - Parent aggregators: - [`studio-isis-gpu-worker.md`](./studio-isis-gpu-worker.md) - [`studio-isis-generation-api.md`](./studio-isis-generation-api.md) - Sibling routes: - [`studio-isis-cost-tracking.md`](./studio-isis-cost-tracking.md) - [`studio-isis-content-safety.md`](./studio-isis-content-safety.md) ## Open questions / known gaps - [ ] Recommendations are held in the service's session store — confirm persistence of computed recommendations across restarts - [x] The fallback chain is configured server-side; this view does not edit model priority or pricing - [ ] Route-map subpaths remain advertised contract paths and are not separate deep-link routes in this focused browser slice - [ ] Manual screen-reader, real touch-device, offline-mode, and telemetry delivery passes remain pending outside the automated Playwright checks