V1 Web PWA · Surface walkthrough

Studio · Yemaya · API

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

walked
8sections4 minread
Markdown source
On this page

Context. surface studio · domain yemaya · route /studio/yemaya/api · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/yemaya/api/page.tsx

Last walked. 2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data (2xx), console/page-errors, expected content, screenshot verified; live screen-reader, touch, offline, and telemetry-delivery checks pending a manual AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; body re-derived 2026-06-03 from current source (lane-console architecture)

Purpose#

Hybrid workspace. The load-bearing surfaces are three real, admin-scoped sibling lanes embedded at the bottom — Cross-Domain Integration, Developer SDKs, and External Tool Integrations — each running its own wired console. Above them, the component retains a large legacy expert shell (18 workflow tracks, an Automated API Parity Checks panel, and a Telemetry/Alerting/Runbooks panel) that is entirely client-side and not backed by any /v1 call — it is reference/demo scaffolding, not a live operation.

Entry points#

  • Studio index quick-actions.
  • Breadcrumb chain on this page: Studio › Yemaya Cross-Domain Integration › API.
  • Embedded whole as the "API Lane" inside /studio/yemaya/database.
  • Direct URL / bookmark (signed-in + studio entitlement).

Layout regions#

page.tsx renders ShellLayout active="studio" and:

  • Breadcrumbs panel (data-yemaya-api-breadcrumbs): Studio › Yemaya Cross-Domain Integration › API (current aria-current="page").
  • Workspace panel (StudioYemayaApiWorkspace, data-yemaya-api-workspace):
    • <h1> "Yemaya API Workspace".
    • Summary <p data-yemaya-api-summary>.
    • Capability Summary (data-yemaya-api-capability-summary, <h2>): four data-yemaya-api-capability cards — API Contract Orchestration, SDK and Client Operations, Integration and Runtime Governance, Security and Parity.
    • Legacy workflow-track shell (no /v1): 18 <section> tracks (one per YEMAYA_API_WORKFLOW_TRACKS entry, each keyed by its dataAttribute), each listing data-yemaya-api-workflow-row articles with a "Force failure" checkbox (data-yemaya-api-workflow-failure-toggle), a "Run workflow" button (data-yemaya-api-workflow-run), and …-workflow-status / …-workflow-runs readouts; plus data-yemaya-api-workflow-notice and data-yemaya-api-workflow-summary.
    • Automated API Parity Checks (data-yemaya-api-parity, <h2>, no /v1): "Run API parity checks" button (data-yemaya-api-parity-run), data-yemaya-api-parity-last-run, and data-yemaya-api-parity-report rows.
    • Telemetry, Alerting, and Runbooks (data-yemaya-api-telemetry, <h2>, static): data-yemaya-api-alert-channel cards and data-yemaya-api-runbook-link anchors.
    • Cross-Domain Integration Lane (data-yemaya-api-cross-domain-lane, <h2>) — embeds StudioYemayaCrossDomainIntegrationWorkspace (real, wired).
    • Developer SDKs Lane (data-yemaya-api-sdks-lane, <h2>) — embeds StudioYemayaDeveloperSdksWorkspace (real, wired).
    • External Tool Integrations Lane (data-yemaya-api-tool-integrations-lane, <h2>) — embeds StudioYemayaExternalToolIntegrationsWorkspace (real, wired — see studio-yemaya-external-tool-integrations.md).
  • Route Map panel (data-yemaya-api-route-map): <h2> "Route Map" with six entries.
  • Quick-action panel: four quickAction links.

States#

The page itself does not fetch. State lives in two places:

  • Legacy shell (client-only):
    • Run workflow — clicking data-yemaya-api-workflow-run flips that track's …-workflow-status to passed (or failed when its "Force failure" toggle is set) and increments …-workflow-runs; no network call.
    • Run parity checks — data-yemaya-api-parity-run derives pass/fail rows from the in-page workflow statuses; no network call.
  • Embedded lanes (real): each owns loading / unauthorized (admin-scope 401/403) / error / ready-form / result — see the per-lane walkthroughs.

Interactions#

Capability cards (non-interactive)#

  • API Contract Orchestration / SDK and Client Operations / Integration and Runtime Governance / Security and Parity (data-yemaya-api-capability articles).

Legacy workflow-track shell (client-only)#

  • "Force failure" checkbox (data-yemaya-api-workflow-failure-toggle) per workflow row.
  • "Run workflow" button (data-yemaya-api-workflow-run) per workflow row.
  • "Run API parity checks" button (data-yemaya-api-parity-run).
  • Runbook links (data-yemaya-api-runbook-link) — static <a href> to /docs/runbooks/yemaya-api/....

Embedded lanes (real)#

Route map#

data-yemaya-api-route-map — six entries:

  • /studio/yemaya/api
  • /studio/yemaya/api/endpoints/[endpointId]
  • /studio/yemaya/api/clients/[clientId]
  • /studio/yemaya/api/integrations/[integrationId]
  • /studio/yemaya/api/parity/[parityId]
  • /studio/yemaya/api/governance/[policyId]

Quick actions#

  • "Open Yemaya Cross-Domain Integration workspace" → /studio/yemaya/cross-domain-integration.
  • "Open Yemaya Developer SDKs workspace" → /studio/yemaya/developer-sdks.
  • "Open Yemaya External Tool Integrations workspace" → /studio/yemaya/external-tool-integrations.
  • "Back to Studio workspace index" → /studio.

Data & contracts#

  • Reads: none at the page boundary. The legacy shell makes no /v1 call; the three embedded lanes each GET their own admin-scoped catalog (fetch on mount, buildBffAuthHeaders(), cache: 'no-store').
  • Writes: none at the page boundary. The legacy "Run workflow" / "Run parity checks" mutate React state only; the embedded lanes own their real POSTs.
  • Realtime: None.
  • Caching: aggregator delegates to embedded lanes.
  • Auth/role check: admin-scoped, fail-closed inside each embedded lane; route additionally signed-in + studio via the proxy gate. The legacy shell is not auth-gated because it is client-only scaffolding.

Cross-references#

  • Workspace source: apps/oshun/web/src/components/studio/StudioYemayaApiWorkspace.tsx
  • Route map source: apps/oshun/web/src/components/studio/StudioYemayaApiRouteMap.ts
  • Page source: apps/oshun/web/src/app/studio/yemaya/api/page.tsx
  • Embedded lanes:
    • apps/oshun/web/src/components/studio/StudioYemayaCrossDomainIntegrationWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioYemayaDeveloperSdksWorkspace.tsx
    • apps/oshun/web/src/components/studio/StudioYemayaExternalToolIntegrationsWorkspace.tsx
  • Embedded in: studio-yemaya-database.md
  • Studio overview: studio-overview.md
  • Feature spec: V1/features.md

Open questions / known gaps#

  • The 18-track workflow shell, Automated API Parity Checks, and Telemetry/Alerting/Runbooks panels have no backend — "Run workflow" / "Run parity checks" only mutate local state and the endpoints/actors/alert thresholds are reference data. Confirm whether this scaffolding should be removed or wired to real BFF endpoints.
  • The runbook anchors point at /docs/runbooks/yemaya-api/...; verify those docs exist.
  • Route-map children (endpoints/clients/integrations/parity/ governance) are a sitemap contract; confirm which dynamic pages exist.