V1 Web PWA · Surface walkthrough

Studio · Isis · Intelligent Routing

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/intelligent-routing · auth signed-in Studio shell + Studio Isis route boundary; admin-scoped BFF · source apps/oshun/web/src/app/studio/isis/intelligent-routing/page.tsx

Last walked. 2026-07-01 focused Playwright + unit/BFF verification: direct boundary, authenticated localhost lane, live BFF fallback decisions, validation, pending, malformed/error/network, unauthorized, anonymous redirect, route map, quick-actions, and touch targets.

Purpose#

Admin lane console for model-routing decisions. The operator supplies a route id, the current model, a routing reason, and an optional required context window; the router computes a routing decision with its fallback chain. Reads the routing context and computes routes via /v1/admin/isis/intelligent-routing; admin-scoped and fail-closed.

Entry points#

  • Sibling quick-action from /studio/isis/provider-factory
  • Studio index (/studio)
  • Direct URL / bookmark

Layout regions#

page.tsx mounts <ShellLayout active="studio"> (no breadcrumb panel) and three panels: the workspace, the Route Map, and sibling quick-actions.

  • Header: shell header
  • Workspace panel (data-isis-intelligent-routing-workspace):
    • <h1> (WorkspaceHeading) "Isis Intelligent Routing Workspace"
    • Summary paragraph (data-routing-summary)
    • Compute form (data-routing-form)
    • Decision result (data-routing-result, with data-routing-decision / data-routing-has-decision / data-routing-noroute) and the fallback chain (<h2>Fallback chain</h2>, data-routing-chain, data-routing-chain-entry)
    • Routing decisions list (data-routing-list, <h2>Routing decisions</h2>, data-routing-record=<routeId>); empty state data-routing-empty
  • Route Map panel (data-isis-intelligent-routing-route-map): <h2>Route Map</h2> over the route map (5 entries)
  • Sibling quick-actions panel: /studio/isis/provider-factory, /studio

States#

  • Loading — data-routing-loading
  • Unauthorized — 401/403 admin-scope fail-closed; data-routing-unauthorized
  • Error — non-OK / malformed; data-routing-error
  • Ready (form) — compute form + decision list render
  • Result — data-routing-result after computing (data-routing-status); no-route case → data-routing-noroute
  • Empty — no routing decisions yet; data-routing-empty

Interactions#

Compute form (data-routing-form)#

  • Route id (data-routing-id, input)
  • Current model (data-routing-model, input)
  • Reason (data-routing-reason, <select>)
  • Required context window (optional) (data-routing-ctx, input)
  • Compute route (data-routing-run) — POST /v1/admin/isis/intelligent-routing

Route Map#

  • Route-map articles ×5

Sibling quick-actions#

  • Open Isis Provider Factory workspace → /studio/isis/provider-factory
  • Back to Studio workspace index → /studio

Data & contracts#

  • Reads: GET /v1/admin/isis/intelligent-routing (generated timestamp, fallback chain, reasons, existing routes)
  • Writes: POST /v1/admin/isis/intelligent-routing (routeId, currentModel, reason, optional positive-integer requiredContextWindow; returns the stored route record with a decision or null)
  • Realtime: none
  • Caching: client fetch on mount, cache: 'no-store', buildBffAuthHeaders()
  • Auth/role check: direct route is hard-blocked by the Studio Isis boundary; localhost E2E lane reaches the signed-in shell; BFF remains admin-scoped and fail-closed (401/403)
  • Component sources:
    • apps/oshun/web/src/components/studio/StudioIsisIntelligentRoutingWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioIsisIntelligentRoutingRouteMap.ts

Automated coverage#

  • apps/oshun/web/e2e/studio-isis-intelligent-routing.spec.ts
    • direct Studio Isis boundary hard-block
    • authenticated localhost lane loads live BFF chain, seeded route decisions, route map, sibling quick-actions, and touch-sized controls
    • browser GET/POST auth headers are forwarded to the live BFF
    • live cost-threshold, rate-limit, required-context-floor, duplicate, and terminal-model no-route paths
    • direct BFF invalid off-chain model and bad-reason payloads
    • client invalid-context validation and pending disabled state
    • loading, service failure, malformed catalog, malformed POST record, network failure, unauthorized scope, and anonymous redirect
  • apps/oshun/web/src/components/__tests__/StudioIsisIntelligentRoutingWorkspace.test.tsx covers ready, unauthorized, service-error, and malformed-catalog rendering.
  • apps/oshun/web/src/components/__tests__/StudioIsisIntelligentRoutingWorkspace.integration.test.tsx covers POST payload construction, duplicate rejection, invalid context, and malformed successful POST records.
  • apps/oshun/bff/src/__tests__/admin-isis-intelligent-routing-route.test.ts covers auth/scope, listing, cost/context/rate-limit selection, context floors, null decisions, duplicate ids, off-chain models, and invalid reasons.

Cross-references#

Open questions / known gaps#

  • No breadcrumb on this route — navigation via sibling quick-actions
  • Route-map sub-paths are declared but not yet implemented as separate pages