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

# Studio · Isis · Intelligent Routing

## 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

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

## Interactions

### Compute form (`data-routing-form`)

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

### Route Map

- [x] **Route-map articles** ×5

### Sibling quick-actions

- [x] **Open Isis Provider Factory workspace** → `/studio/isis/provider-factory`
- [x] **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

- Studio overview: [`../../studio-overview.md`](../../studio-overview.md)
- Sibling routes:
  - [`studio-isis-provider-factory.md`](./studio-isis-provider-factory.md)
  - [`studio-isis-provider-integration.md`](./studio-isis-provider-integration.md)

## 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