Disciplines · Decisions (ADRs)

ADR-0046: OSHUN Studio API Gateway and BFF Composition

OSHUN Studio is exposing increasingly complex cross-domain workflows for AAA games, cinematic pipelines, orchestration, governance, and compliance.

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

Status: Accepted
Date: 2026-02-23
Authors: OSHUN Studio Architecture, OSHUN Web Engineering, OSHUN BFF Engineering, OSHUN Security Engineering
Reviewers: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project Obsidian Program Design, Platform SRE

Context and Problem Statement#

OSHUN Studio is exposing increasingly complex cross-domain workflows for AAA games, cinematic pipelines, orchestration, governance, and compliance. Domain-local APIs already exist, but composition strategy across Studio surfaces is inconsistent and can fragment policy, latency, observability, and release confidence.

Without a canonical API gateway and BFF composition model, Studio risks:

  • inconsistent contract shaping and response semantics across domains
  • duplicated authz/entitlement/policy enforcement in web clients
  • fragile aggregation under partial failures and high-latency dependencies
  • weak traceability and auditability for cross-domain workflow execution

Decision Drivers#

  • Consistency: one composition contract across Studio web surfaces.
  • Safety: centralized policy enforcement at gateway and BFF boundaries.
  • Reliability: resilient aggregation with deterministic degraded modes.
  • Performance: bounded latency for multi-domain orchestration paths.
  • Operability: clear telemetry, tracing, and ownership for incident response.

Considered Options#

Option 1: Domain-Direct Client Calls#

Studio clients call each domain API directly and compose locally.

Pros:

  • Minimal BFF changes.

Cons:

  • Security and policy logic spreads across clients.
  • Inconsistent contracts and unstable orchestration latency.
  • Harder cross-domain observability and incident diagnostics.

Option 2: Thin Proxy Gateway with Minimal Composition#

Gateway forwards requests but keeps composition mostly in domain services.

Pros:

  • Lower short-term implementation complexity.

Cons:

  • Limited contract normalization and weak cross-domain workflow guarantees.
  • Incomplete control over retries, fallback behavior, and audit context.

Option 3: Canonical Policy-Aware API Gateway + BFF Composition Layer (Chosen)#

Adopt a typed gateway/BFF contract model that centralizes authz, entitlement, policy gates, orchestration, resiliency, and observability for Studio workflows.

Pros:

  • Deterministic cross-domain contracts and orchestration behavior.
  • Stronger security posture with centralized policy guardrails.
  • Better resilience, diagnostics, and release-readiness controls.

Cons:

  • Requires disciplined schema governance and version management.

Decision Outcome#

Chosen option: Option 3.

API gateway and BFF composition requirements:

  1. Canonical route and envelope contracts for Studio workflows.
  2. Centralized authz/entitlement/policy enforcement at middleware and route boundaries.
  3. Deterministic aggregation/orchestration semantics with explicit degradation contracts.
  4. SLO-aware latency and failure budgets for composition paths.
  5. Telemetry/audit/tracing contracts for end-to-end accountability.

Normative Rules#

Gateway and Contract Rule#

  • Studio workflows must enter through governed gateway/BFF routes.
  • Response envelopes must be schema-versioned and domain-attributed.
  • Breaking response changes require versioned route transitions.

Policy Enforcement Rule#

  • Authn/authz/entitlements and scope policy checks execute before composition.
  • Policy decisions must be auditable with actor, scope, and decision reason.
  • Client-side bypass of privileged policy checks is prohibited.

Composition and Resilience Rule#

  • Multi-domain workflows must declare dependency order and fallback semantics.
  • Partial-failure behavior must be deterministic and user-visible.
  • Retry budgets and timeout ceilings must be bounded per route tier.

Observability and Release Rule#

  • Composition flows must emit tracing spans, audit events, and SLO metrics.
  • Release gates must block on unresolved critical policy or latency regressions.
  • Production incident paths require runbook-backed escalation ownership.

Architecture Implications#

  • apps/oshun/bff remains authoritative for cross-domain Studio composition.
  • Gateway/BFF middleware layers become mandatory policy and tracing boundaries.
  • Domain adapters standardize composition inputs/outputs for Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian workflows.
  • Observability dashboards and on-call runbooks integrate route-level SLO signals and degradation indicators.

Acceptance Criteria (OST-00265)#

OST-00265 is complete only when:

  1. ADR exists at docs/adr/ADR-0052-oshun-studio-api-gateway-and-bff-composition.md.
  2. ADR defines options, trade-offs, and selected strategy.
  3. ADR defines gateway contract, policy, composition/resilience, and observability/release rules.
  4. ADR aligns with ADR-0007 through ADR-0045, especially ADR-0007, ADR-0010, ADR-0012, ADR-0022, and ADR-0041.
  5. ADR aligns with current BFF implementation surfaces in apps/oshun/bff.
  6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

Consequences#

Positive#

  • Stronger and more predictable cross-domain Studio orchestration.
  • Improved policy integrity and auditability for privileged workflows.
  • Better reliability and incident diagnostics across composition paths.

Negative#

  • Higher governance overhead for route and schema lifecycle management.
  • Requires strict coordination across web, BFF, security, and domain teams.
  • docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md
  • docs/adr/ADR-0016-shared-identity-and-cross-domain-session-model.md
  • docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md
  • docs/adr/ADR-0028-oshun-studio-cross-domain-entity-model.md
  • docs/adr/ADR-0047-oshun-studio-observability-and-operational-dashboards.md

References#

  • 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