Disciplines · Decisions (ADRs)

ADR-0048: OSHUN Studio SDK and Documentation Integration

Studio now exposes a growing set of governance and execution capabilities across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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 Developer Experience, OSHUN Security Engineering
Reviewers: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project Obsidian Program Design, Compliance

Context and Problem Statement#

Studio now exposes a growing set of governance and execution capabilities across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian. Teams need a single integration surface where:

  • API contracts are discoverable and versioned.
  • SDKs are generated and distributed with consistent behavior.
  • Documentation and runnable examples stay synchronized with contracts.
  • Policy, audit, and release controls remain enforceable.

Without a canonical SDK/documentation integration model, Studio risks:

  • divergent SDK quality and language support across domains
  • stale or conflicting documentation relative to runtime contracts
  • increased integration failures from contract/SDK version drift
  • weaker governance traceability for sensitive integration changes

Decision Drivers#

  • Contract integrity: one authoritative contract source for docs and SDKs.
  • Developer ergonomics: consistent onboarding and usage across domains.
  • Governance: explicit policy and audit controls for integration artifacts.
  • Reliability: deterministic SDK/doc publishing and rollback behavior.
  • Scale: support for multi-domain, multi-language integration growth.

Considered Options#

Option 1: Domain-Local SDK and Docs Pipelines#

Each domain owns independent spec, SDK, docs generation, and publication.

Pros:

  • High local autonomy and rapid domain-specific iteration.

Cons:

  • Inconsistent SDK quality and documentation format.
  • Cross-domain integrations become difficult to reason about and govern.

Option 2: Documentation-Only Portal With Manual SDK Guidance#

Publish unified docs but keep SDK generation/manual examples outside Studio.

Pros:

  • Lower implementation effort in the short term.

Cons:

  • SDK drift and hand-maintained examples create reliability issues.
  • Weak enforceability for version compatibility and governance controls.

Option 3: Canonical Studio SDK + Documentation Integration Framework (Chosen)#

Adopt one integration framework where typed contracts drive SDK generation, documentation assembly, sample validation, and governance evidence.

Pros:

  • Deterministic docs/SDK alignment with clear version semantics.
  • Better onboarding, reliability, and cross-domain integration consistency.
  • Stronger policy/audit controls for integration lifecycle changes.

Cons:

  • Requires central governance and release orchestration discipline.

Decision Outcome#

Chosen option: Option 3.

Studio SDK/documentation integration requirements:

  1. Contract-first lifecycle for OpenAPI/typed schemas and compatibility policies.
  2. Generated SDK surfaces with standardized auth, errors, retries, and telemetry hooks.
  3. Integrated documentation portal with synchronized API reference, guides, and code samples.
  4. Governed release workflow with policy checks, audit evidence, and rollback readiness.
  5. Cross-domain coverage for Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

Normative Rules#

Contract Source of Truth Rule#

  • Contract artifacts (OpenAPI/schemas) are authoritative for SDK/doc generation.
  • Breaking changes require explicit version migration strategy and approvals.
  • Generated docs and SDKs must reference the same contract digest/version.

SDK Generation and Runtime Behavior Rule#

  • SDKs must expose consistent auth, request/response typing, error envelopes, retry/idempotency semantics, and correlation metadata.
  • SDK lifecycle must include deterministic publish/rollback channels.
  • Generated SDK metadata must include source contract version and generated-at timestamp.

Documentation Assembly Rule#

  • API reference, guides, code samples, and policy notes must be published from the same release context as SDK artifacts.
  • Example snippets must be contract-validated and runnable in CI validation suites.
  • Deprecated endpoints/contracts must include migration guidance and timelines.

Governance and Security Rule#

  • Sensitive integration changes require role/tier/approval controls.
  • SDK/doc publication and policy decisions must emit audit events.
  • Production releases must preserve traceability across actor, artifact, and contract version.

Observability and Reliability Rule#

  • Integration workflow telemetry must include generation, validation, publish, and rollback outcomes.
  • SLOs must cover generation success rate, publication latency, and doc/sdk consistency health.
  • Degraded observability states must block production promotion until resolved.

Architecture Implications#

  • Studio adds first-class SDK/documentation integration workspace surfaces.
  • BFF contract artifacts become primary inputs for SDK/doc pipelines.
  • Domain teams align integration artifacts to centralized contract governance.
  • Documentation publishing and SDK distribution workflows require shared policy and telemetry hooks.

Acceptance Criteria (OST-00281)#

OST-00281 is complete only when:

  1. ADR exists at docs/adr/ADR-0054-oshun-studio-sdk-and-documentation-integration.md.
  2. ADR defines options, trade-offs, and selected strategy.
  3. ADR defines contract-source, SDK generation, documentation assembly, governance/security, and observability/reliability rules.
  4. ADR aligns with ADR-0007 through ADR-0047, especially ADR-0007, ADR-0012, ADR-0046, and ADR-0047.
  5. ADR aligns with existing contract and SDK/documentation implementation surfaces.
  6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

Consequences#

Positive#

  • Unified developer experience for Studio integrations.
  • Higher confidence in SDK/doc consistency and contract safety.
  • Stronger operational governance for integration lifecycle changes.

Negative#

  • Additional operational overhead for centralized release governance.
  • Requires coordinated contract/version discipline across all domain teams.
  • docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md
  • docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md
  • docs/adr/ADR-0052-oshun-studio-api-gateway-and-bff-composition.md
  • docs/adr/ADR-0053-oshun-studio-webhooks-and-external-automation.md

References#

  • apps/oshun/bff/openapi/oshun-bff.openapi.yaml
  • apps/oshun/bff/README.md
  • apps/iris/api/src/docs/index.ts
  • apps/isis/cli/src/commands/generate.ts
  • apps/lilith/svc-ai/src/integration-api/index.ts
  • libs/nyx/client-python/README.md
  • docs/releases/v1/runbooks/on-call-runbook.md