# ADR-0046: OSHUN Studio API Gateway and BFF Composition

**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.

## Related Decisions

- `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`