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.mddocs/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#
- Every composed workflow is route-contract-backed and versioned.
- Policy and entitlement checks execute before privileged composition.
- Partial failures must degrade predictably with explicit user-visible state.
- 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:
- Define route path, method, and workflow reference.
- Bind source domains and release-channel scope.
- Validate contract version and schema compatibility.
- Publish route definition to registry.
- 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:
- Ingest request envelope with actor/workspace/trace identity.
- Enforce authz/entitlement/scope policy checks.
- Execute domain adapter fan-out per composition plan.
- Aggregate normalized responses into canonical envelope.
- 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:
- Detect failing dependency and classify severity.
- Apply fallback strategy (
cached,partial, orminimal). - Mark response envelope with degraded-mode semantics.
- Emit resilience event and dependency health update.
- 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:
- Evaluate actor role, permission tier, and entitlements.
- Validate production approval prerequisites where required.
- Allow or deny route action with reason code.
- Persist decision evidence for compliance/audit.
- 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:
- Correlate traces, dependency health, and route error signals.
- Apply mitigation (rollback, timeout patch, fallback tuning).
- Re-run composition validation and policy checks.
- Confirm latency/error SLO recovery.
- 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.startedapi_gateway_bff_composition.journey.step.completedapi_gateway_bff_composition.journey.blockedapi_gateway_bff_composition.journey.degradedapi_gateway_bff_composition.journey.recoveredapi_gateway_bff_composition.journey.completed
Required dimensions:
requestId,routePath,method,workflowRef,sourceDomainsactorId,actorRole,permissionTier,entitlements,releaseChanneltraceId,degradedMode,fallbackStrategy,dependencyDomainpolicyOutcome,reasonCode,journeyId,stepId,latencyMs,outcome
5. Acceptance Criteria (OST-00267)#
OST-00267 is complete only when:
- At least five API gateway/BFF composition journeys are documented.
- At least ten deterministic edge cases are documented.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements and dimensions are documented.