# OSHUN Studio API Gateway and BFF Composition Journeys and Edge Cases

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`
- `docs/releases/v1/specs/studio-api-gateway-and-bff-composition-dependency-and-data-contract-map.md`

## Purpose

Define primary journeys and deterministic edge-case behavior for Studio API
gateway and BFF composition workflows.

This document is the execution artifact for `OST-00267`.

## Personas

- Platform API Operator
- Web Composition Engineer
- Security Reviewer
- SRE Incident Commander
- Compliance Auditor

## Journey Principles

1. Every composed workflow is route-contract-backed and versioned.
2. Policy and entitlement checks execute before privileged composition.
3. Partial failures must degrade predictably with explicit user-visible state.
4. Tracing, audit evidence, and SLO signals must be emitted for all flows.

## 1. Primary Journeys

### J1. Register or Evolve Gateway Route Contract

**Goal**: Publish a governed route contract for Studio workflow composition.

**Entry**: `API gateway/BFF composition workspace`

**Steps**:

1. Define route path, method, and workflow reference.
2. Bind source domains and release-channel scope.
3. Validate contract version and schema compatibility.
4. Publish route definition to registry.
5. Emit route-publish governance audit event.

**Success State**:

- Route contract is versioned, discoverable, and policy-ready.

### J2. Execute Multi-Domain Composed Request

**Goal**: Serve a deterministic composed response from authorized domains.

**Entry**: `Studio route request (web shell)`

**Steps**:

1. Ingest request envelope with actor/workspace/trace identity.
2. Enforce authz/entitlement/scope policy checks.
3. Execute domain adapter fan-out per composition plan.
4. Aggregate normalized responses into canonical envelope.
5. Emit response metrics, traces, and audit event.

**Success State**:

- Response is policy-compliant, typed, and latency-budgeted.

### J3. Apply Degraded Composition Under Partial Failure

**Goal**: Keep workflow operable when one or more dependencies degrade.

**Entry**: `Downstream domain timeout/degradation signal`

**Steps**:

1. Detect failing dependency and classify severity.
2. Apply fallback strategy (`cached`, `partial`, or `minimal`).
3. Mark response envelope with degraded-mode semantics.
4. Emit resilience event and dependency health update.
5. Surface deterministic recovery guidance to operators.

**Success State**:

- Workflow remains safe and diagnosable under partial dependency failure.

### J4. Decide Sensitive Route Access and Release Action

**Goal**: Enforce policy controls for sensitive/restricted composition routes.

**Entry**: `Privileged route invocation or release promotion`

**Steps**:

1. Evaluate actor role, permission tier, and entitlements.
2. Validate production approval prerequisites where required.
3. Allow or deny route action with reason code.
4. Persist decision evidence for compliance/audit.
5. Emit policy decision and denial/allow audit events.

**Success State**:

- Sensitive actions are centrally governed and fully auditable.

### J5. Recover Composition Health After Incident

**Goal**: Restore route reliability and close incident with evidence.

**Entry**: `SLO breach or on-call incident trigger`

**Steps**:

1. Correlate traces, dependency health, and route error signals.
2. Apply mitigation (rollback, timeout patch, fallback tuning).
3. Re-run composition validation and policy checks.
4. Confirm latency/error SLO recovery.
5. Publish incident closure and postmortem references.

**Success State**:

- Composition path is restored with verified reliability and audit trail.

## 2. Critical Edge Cases

### E1. Route Definition Missing Version

- Trigger: route published without `version`.
- Required behavior: reject publish and require explicit version metadata.

### E2. Unsupported Domain in Composition Plan

- Trigger: route references unknown domain target.
- Required behavior: hard reject contract and emit dependency-resolution error.

### E3. Scope-Less Token on Composed Route

- Trigger: actor token lacks domain scopes for route.
- Required behavior: deny request before adapter fan-out and audit denial.

### E4. Dependency Timeout Above Route Budget

- Trigger: downstream call exceeds bounded timeout budget.
- Required behavior: apply deterministic fallback and emit resilience event.

### E5. Mixed Schema Versions Across Domains

- Trigger: adapter payload versions are incompatible for aggregation.
- Required behavior: block aggregation and return version-mismatch error
  envelope.

### E6. Duplicate Request Replay Without Idempotency

- Trigger: same request ID reprocessed in a non-idempotent path.
- Required behavior: reject replay and emit replay-protection audit event.

### E7. Production Sensitive Route Without Approval Evidence

- Trigger: restricted production action lacks approval ticket.
- Required behavior: hard deny action and require approval reference.

### E8. Missing Trace Correlation Across Adapter Calls

- Trigger: downstream spans cannot correlate with gateway trace.
- Required behavior: fail observability check and raise composition incident.

### E9. Stale Fallback Cache Beyond TTL

- Trigger: degraded response uses expired cache payload.
- Required behavior: block stale fallback and return explicit degraded-minimal
  envelope.

### E10. Audit Event Emission Failure

- Trigger: gateway cannot emit audit event for decision/response.
- Required behavior: mark request as degraded-observability and alert on-call.

## 3. Journey-to-Surface Mapping

| Journey                           | Primary Surface                     | Supporting Surfaces                                |
| --------------------------------- | ----------------------------------- | -------------------------------------------------- |
| J1 Register/Evolve Route Contract | Gateway route governance panel      | Contract registry + schema controls                |
| J2 Execute Composed Request       | Runtime composition execution panel | Authz middleware + domain adapters + aggregator    |
| J3 Apply Degraded Composition     | Resilience/degradation panel        | Timeout policy engine + fallback services          |
| J4 Decide Sensitive Route Access  | Policy decision panel               | Entitlement service + approval governance controls |
| J5 Recover Composition Health     | Incident recovery panel             | Tracing + metrics dashboards + on-call workflows   |

## 4. Instrumentation Requirements

Required events:

- `api_gateway_bff_composition.journey.started`
- `api_gateway_bff_composition.journey.step.completed`
- `api_gateway_bff_composition.journey.blocked`
- `api_gateway_bff_composition.journey.degraded`
- `api_gateway_bff_composition.journey.recovered`
- `api_gateway_bff_composition.journey.completed`

Required dimensions:

- `requestId`, `routePath`, `method`, `workflowRef`, `sourceDomains`
- `actorId`, `actorRole`, `permissionTier`, `entitlements`, `releaseChannel`
- `traceId`, `degradedMode`, `fallbackStrategy`, `dependencyDomain`
- `policyOutcome`, `reasonCode`, `journeyId`, `stepId`, `latencyMs`, `outcome`

## 5. Acceptance Criteria (OST-00267)

`OST-00267` is complete only when:

1. At least five API gateway/BFF composition journeys are documented.
2. At least ten deterministic edge cases are documented.
3. Journey-to-surface mapping is explicit.
4. Instrumentation requirements and dimensions are documented.
