Studio · Yemaya · Cross-Domain Integration

Purpose#

Admin lane console for the cross-domain event-mapping validator. The Cross-Domain Event Mapping Lane wires /v1/admin/yemaya/cross-domain-integration: author a source-event → target-handler mapping with field mappings and validate it against the Oshun domain registry — source/target fields must exist, mapped types must match, and every required target field must be covered.

Entry points#

• No breadcrumb panel on this page.
• Reachable from the Studio index and from the Community Features quick-action (which links here).
• Embedded as the Cross-Domain Integration Lane inside the Event Handlers aggregator (/studio/yemaya/event-handlers).
• Direct URL / bookmark (signed-in + studio entitlement).

Layout regions#

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

• Workspace panel (StudioYemayaCrossDomainIntegrationWorkspace, data-yemaya-cross-domain-integration-workspace):
  • <h1> "Yemaya Cross-Domain Integration Workspace" (WorkspaceHeading).
  • Summary paragraph (data-yemaya-cross-domain-integration-summary).
  • Cross-Domain Event Mapping Lane — <h2> data-yemaya-cdi-lane-heading, the real-backed form lane (loading / unauthorized / error / ready-form / result, see States).
• Route Map panel (data-yemaya-cross-domain-integration-route-map): <h2> "Route Map" + five STUDIO_YEMAYA_CROSS_DOMAIN_INTEGRATION_ROUTE_MAP entries.
• Quick-action panel: two quickAction links.

States#

• Loading — data-yemaya-cdi-loading "Loading mapping validator…" while the GET catalog fetch is in flight.
• Unauthorized — data-yemaya-cdi-unauthorized "Access restricted." on a 401/403 admin-scope failure (fail-closed).
• Error — data-yemaya-cdi-error "Could not load the mapping validator." on a non-OK / malformed catalog response.
• Ready-form — data-yemaya-cdi-form once the catalog (events, handlers) resolves; data-yemaya-cdi-engine-summary.
• Result — data-yemaya-cdi-result with data-yemaya-cdi-headline (data-ready true/false + error/warning counts), data-yemaya-cdi-coverage, and a data-yemaya-cdi-issues-list (or data-yemaya-cdi-clean); or a validation message data-yemaya-cdi-validate-error.

Interactions#

Mapping form (data-yemaya-cdi-form)#

• Source event — select data-yemaya-cdi-source (aria-label "source event") populated from catalog.events.
• Target handler — select data-yemaya-cdi-target (aria-label "target handler") populated from catalog.handlers; data-yemaya-cdi-required-hint lists the required target fields.
• Field-mapping rows (data-yemaya-cdi-rows) — each data-yemaya-cdi-mapping-row has a data-yemaya-cdi-from (source field) and data-yemaya-cdi-to (target field) select plus data-yemaya-cdi-remove-row; data-yemaya-cdi-add-row "Add mapping" adds a row.
• Submit — button data-yemaya-cdi-submit "Validate mapping" → POST /v1/admin/yemaya/cross-domain-integration/validate with { sourceEvent, targetHandler, fieldMappings }.

Route map#

data-yemaya-cross-domain-integration-route-map — five entries:

• /studio/yemaya/cross-domain-integration
• /studio/yemaya/cross-domain-integration/scenes/[sceneId]
• /studio/yemaya/cross-domain-integration/exports/[exportId]
• /studio/yemaya/cross-domain-integration/revisions/[revisionId]
• /studio/yemaya/cross-domain-integration/governance/[policyId]

Quick actions#

• "Open Yemaya Community Features workspace" → /studio/yemaya/community-features.
• "Back to Studio workspace index" → /studio.

Data & contracts#

• Reads: GET /v1/admin/yemaya/cross-domain-integration (catalog: summary, events, handlers) on mount.
• Writes: POST /v1/admin/yemaya/cross-domain-integration/validate.
• Realtime: none.
• Caching: client fetch on mount, cache: 'no-store', buildBffAuthHeaders().
• Auth/role check: admin-scoped fail-closed (401/403 → unauthorized state) behind the proxy studio gate.

Cross-references#

• Studio overview: studio-overview.md
• Workspace source: apps/oshun/web/src/components/studio/StudioYemayaCrossDomainIntegrationWorkspace.tsx
• Route map source: apps/oshun/web/src/components/studio/StudioYemayaCrossDomainIntegrationRouteMap.ts
• Parent aggregator: studio-yemaya-event-handlers.md
• Sibling Yemaya bridges: see folder index
• Feature spec: V1/features.md

Open questions / known gaps#

• The summary paragraph still advertises "dense expert-mode controls, progressive disclosure" — leftover legacy copy; the live surface is the single Cross-Domain Event Mapping Lane.
• The Route Map advertises scenes / exports / revisions / governance sub-routes that the live lane does not expose.