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

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.
