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.mddocs/adr/ADR-0010-shared-identity-and-cross-domain-session-model.mddocs/adr/ADR-0012-analytics-taxonomy-and-event-naming.mddocs/adr/ADR-0022-oshun-studio-cross-domain-entity-model.mddocs/adr/ADR-0041-oshun-studio-observability-and-operational-dashboards.mddocs/adr/ADR-0046-oshun-studio-api-gateway-and-bff-composition.mdapps/oshun/bff/src/app.tsapps/oshun/bff/src/server.tsapps/oshun/bff/src/routes/home.tsapps/oshun/bff/src/routes/continue.tsapps/oshun/bff/src/routes/domains.tsapps/oshun/bff/src/adapters/domain-service-adapters.tsapps/oshun/bff/src/middleware/authz.tsapps/oshun/bff/src/middleware/entitlements.tsapps/oshun/bff/src/middleware/tracing.tsapps/oshun/bff/src/observability/metrics.tsapps/oshun/bff/openapi/oshun-bff.openapi.yamldocs/releases/v1/runbooks/on-call-runbook.mddocs/domains/yemaya/features.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/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:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for route definitions, request/response composition, dependency status, policy decisions, resilience events, and governance audits are documented.
- Ownership boundaries and validation rules are explicit.