V1 Web PWA · Surface walkthrough

Isis Resource Recommendations

A per-surface walkthrough of the V1 Web PWA studio surface: layout, states, interactions, data, and cross-references.

walked
9sections3 minread
Markdown source
On this page

Context. surface studio · domain isis · route /studio/isis/resource-recommendations · 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

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

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):
    • <h1> "Isis Resource Recommendations Workspace" (WorkspaceHeading)
    • Summary paragraph (data-recommend-summary)
    • Fallback chain (data-recommend-chain, <h2>) of priority-ordered data-recommend-chain-entry cards
    • The "Request a downgrade recommendation" form (data-recommend-form)
    • Recommendation list (data-recommend-list, <h2>) of data-recommend-record cards carrying data-recommend-has-downgrade
  • Route map panel (data-isis-resource-recommendations-route-map): <h2> "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#

  • Loading — data-recommend-loading "Loading recommendations…"
  • Unauthorized — data-recommend-unauthorized (admin-scope fail-closed on 401/403)
  • Error — data-recommend-error on non-OK / malformed response
  • Ready (form) — chain + form + recommendation list render; empty list shows data-recommend-list-empty
  • Result — data-recommend-result with data-recommend-status (ok / error)

Interactions#

Request a downgrade recommendation (data-recommend-form)#

  • Recommendation id — data-recommend-id text input
  • Current model — data-recommend-model select (options from the response chain)
  • Reason — data-recommend-reason select (options from the response reasons)
  • Recommend downgrade — data-recommend-run submit; POSTs to /v1/admin/isis/resource-recommendations, then reloads the list

Route map#

  • Route-map articles — non-interactive path + purpose entries

Quick-actions#

  • Open Isis Content Safety workspace → /studio/isis/content-safety
  • 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#

Open questions / known gaps#

  • Recommendations are held in the service's session store — confirm persistence of computed recommendations across restarts
  • 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