Eve library

OSHUN Studio API Gateway and BFF Composition Dependency and Data Contract Map

Spec

Revision 1

On this page

Status: Active
Owner: OSHUN Studio Architecture + OSHUN Web + OSHUN BFF + Platform SRE + OSHUN Security + OSHUN Data/Analytics Engineering
Last Updated: 2026-02-23
Related: docs/adr/ADR-0046-oshun-studio-api-gateway-and-bff-composition.md

Purpose#

Define dependencies and canonical contracts for Studio API gateway and BFF composition across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

This document is the execution artifact for OST-00266.

Sources Used#

  • docs/adr/ADR-0007-oshun-shell-architecture-and-domain-adapters.md
  • docs/adr/ADR-0010-shared-identity-and-cross-domain-session-model.md
  • docs/adr/ADR-0012-analytics-taxonomy-and-event-naming.md
  • docs/adr/ADR-0022-oshun-studio-cross-domain-entity-model.md
  • docs/adr/ADR-0041-oshun-studio-observability-and-operational-dashboards.md
  • docs/adr/ADR-0046-oshun-studio-api-gateway-and-bff-composition.md
  • apps/oshun/bff/src/app.ts
  • apps/oshun/bff/src/server.ts
  • apps/oshun/bff/src/routes/home.ts
  • apps/oshun/bff/src/routes/continue.ts
  • apps/oshun/bff/src/routes/domains.ts
  • apps/oshun/bff/src/adapters/domain-service-adapters.ts
  • apps/oshun/bff/src/middleware/authz.ts
  • apps/oshun/bff/src/middleware/entitlements.ts
  • apps/oshun/bff/src/middleware/tracing.ts
  • apps/oshun/bff/src/observability/metrics.ts
  • apps/oshun/bff/openapi/oshun-bff.openapi.yaml
  • docs/releases/v1/runbooks/on-call-runbook.md
  • docs/domains/yemaya/features.md
  • docs/domains/isis/features.md
  • docs/domains/hathor/features.md
  • docs/domains/aja/features.md
  • docs/domains/bellona/features.md

1. Dependency Overview#

1.1 Control Surfaces#

  • Gateway route surfaces: composition-aware BFF routes for Studio workflow entrypoints.
  • Domain adapter services: normalized adapters for Yemaya, Isis, Hathor, Aja, and Bellona payloads.
  • Policy and entitlement services: authz + entitlement middleware for scoped workflow authorization.
  • Resilience/orchestration services: timeout, partial-failure, and fallback controls for multi-domain aggregation.
  • Observability services: tracing, route metrics, and error-rate instrumentation.
  • Governance services: audit events and release gate signals for composition integrity.

1.2 Domain Dependency Graph#

  • API Gateway/BFF Composition -> Yemaya: release and operational workflow aggregation.
  • API Gateway/BFF Composition -> Isis: model-workbench orchestration and status composition.
  • API Gateway/BFF Composition -> Hathor: narrative/editor workflow composition.
  • API Gateway/BFF Composition -> Aja: rendering/timeline composition and continuity signals.
  • API Gateway/BFF Composition -> Bellona: runtime safety and policy-governed control surfaces.
  • Project Obsidian -> all: cross-domain workflow choreography and composition governance.

2. Ownership and Contract Matrix#

Area Owner Consumers Artifact Contract
Gateway route registry and semantics OSHUN BFF Web shell + Studio surfaces Route definition catalog StudioGatewayRouteDefinition
Composition request context Web + BFF Gateway middleware + adapters Request envelope StudioBffCompositionRequestEnvelope
Aggregated response and degradation OSHUN BFF + domain teams Studio operators + orchestration Response envelope StudioBffCompositionResponseEnvelope
Dependency health and readiness Platform SRE + BFF Incident responders + dashboards Dependency status stream StudioBffDependencyStatusReport
Policy/entitlement decisioning Security + Compliance Operators + release managers Policy decision envelope StudioBffPolicyDecision
Resilience and fallback execution Platform SRE + BFF On-call + runtime operations Resilience execution events StudioBffResilienceEvent
Governance audit evidence Security + Data Platform Compliance + audit operations Audit event stream StudioBffGovernanceAuditEvent

3. Canonical Contracts#

3.1 StudioGatewayRouteDefinition#

ts
export interface StudioGatewayRouteDefinition {
  routeId: string;
  routePath: string;
  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
  workflowRef: string;
  owner: string;
  sourceDomains: Array<
    'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun'
  >;
  releaseChannelScope: 'preview' | 'staging' | 'production' | 'all';
  version: string;
  createdAt: string;
  updatedAt: string;
}

3.2 StudioBffCompositionRequestEnvelope#

ts
export interface StudioBffCompositionRequestEnvelope {
  requestId: string;
  actorId: string;
  tenantId?: string;
  workspaceId: string;
  routePath: string;
  method: string;
  releaseChannel: 'preview' | 'staging' | 'production';
  entitlements: string[];
  scopes: string[];
  traceId: string;
  requestedAt: string;
}

3.3 StudioBffCompositionResponseEnvelope#

ts
export interface StudioBffCompositionResponseEnvelope {
  requestId: string;
  routePath: string;
  success: boolean;
  latencyMs: number;
  composedDomains: Array<
    'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun'
  >;
  partialFailure: boolean;
  degradedMode:
    | 'none'
    | 'fallback_cached'
    | 'fallback_partial'
    | 'fallback_minimal';
  policyVerdict: 'allowed' | 'denied';
  errorCode?: string;
  respondedAt: string;
}

3.4 StudioBffDependencyStatusReport#

ts
export interface StudioBffDependencyStatusReport {
  reportId: string;
  routePath: string;
  dependencyDomain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'oshun';
  status: 'healthy' | 'degraded' | 'down';
  timeoutMs: number;
  errorRate: number;
  p95LatencyMs: number;
  observedAt: string;
}

3.5 StudioBffPolicyDecision#

ts
export interface StudioBffPolicyDecision {
  decisionId: string;
  requestId: string;
  routePath: string;
  actorId: string;
  actorRole: string;
  permissionTier: 'baseline' | 'sensitive' | 'restricted';
  entitlements: string[];
  outcome: 'allowed' | 'denied';
  reasonCode?: string;
  decidedAt: string;
}

3.6 StudioBffResilienceEvent#

ts
export interface StudioBffResilienceEvent {
  eventId: string;
  requestId: string;
  routePath: string;
  strategy:
    | 'timeout_bounded_retry'
    | 'partial_fallback'
    | 'cached_fallback'
    | 'graceful_degradation';
  success: boolean;
  latencyMs: number;
  downstreamFailures: string[];
  errorCode?: string;
  occurredAt: string;
}

3.7 StudioBffGovernanceAuditEvent#

ts
export interface StudioBffGovernanceAuditEvent {
  eventId: string;
  action:
    | 'bff.route.invoked'
    | 'bff.policy.denied'
    | 'bff.composition.partial_failure'
    | 'bff.resilience.fallback_applied'
    | 'bff.response.emitted';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  requestId?: string;
  routePath?: string;
  actorId?: string;
  actorRole?: string;
  reasonCode?: string;
  occurredAt: string;
}

4. Validation Rules#

  • Route definitions must include owner, method, source domains, and version.
  • Request envelopes must include actor/workspace, scopes, entitlements, and trace identity.
  • Response envelopes must capture latency, degradation mode, and policy verdict.
  • Dependency status reports must expose latency/error/health for each domain dependency.
  • Policy decisions must be deterministic and reason-coded for deny outcomes.
  • Resilience events must capture fallback strategy, downstream failures, and success status.
  • Governance audits must capture route invocation, policy, resilience, and response lifecycle actions end to end.

5. Acceptance Criteria (OST-00266)#

OST-00266 is complete only when:

  1. This dependency and contract map exists.
  2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
  3. Contracts for route definitions, request/response composition, dependency status, policy decisions, resilience events, and governance audits are documented.
  4. Ownership boundaries and validation rules are explicit.