Disciplines · Decisions (ADRs)

ADR-0013: OSHUN Studio Information Architecture and Capability Exposure Model

OSHUN has accepted shell architecture decisions for consumer-facing domain experiences (Tara, Veritas, Nyx, Arete), but OSHUN Studio requires a distinct IA model for expert users building AAA games, films, and cross-media productions.

Accepted · 2026-02-23
11sections5 minread
Markdown source
On this page

Status: Accepted
Date: 2026-02-23
Authors: OSHUN Studio Product, OSHUN Web Engineering, Platform Architecture
Reviewers: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona)
Supersedes: N/A
Superseded by: N/A

Context and Problem Statement#

OSHUN has accepted shell architecture decisions for consumer-facing domain experiences (Tara, Veritas, Nyx, Arete), but OSHUN Studio requires a distinct IA model for expert users building AAA games, films, and cross-media productions.

Studio scope is broader and operationally denser than the consumer shell:

  • Yemaya: project orchestration, assets, collaboration, production operations
  • Isis: generative workflows, GPU operations, outputs, lineage, cost controls
  • Hathor: worldbuilding, narrative, simulation, lore validation
  • Aja: motion capture, retargeting, animation processing pipelines
  • Bellona: engine bridges, build/export, runtime and virtual production
  • Project Obsidian: flagship franchise program that spans all five domains

Without a dedicated IA decision and quality bar, Studio risks:

  • fragmented workflows across domain UIs
  • missing feature exposure for high-value domain capabilities
  • inconsistent expert ergonomics and observability
  • weak cross-domain traceability from idea to shipped artifact

Decision Drivers#

  • Capability completeness: expose all advanced domain capabilities in one web interface.
  • Expert ergonomics: support dense, high-throughput, low-friction workflows.
  • Cross-domain traceability: every action must preserve project/program lineage.
  • Operational safety: explicit validation, approvals, auditability, and rollback paths.
  • Parity governance: web surfaces must stay in lockstep with domain API and event contracts.
  • Performance and resilience: large-scale production workflows must remain responsive under load and partial outages.

Considered Options#

Option 1: Domain-First Separate Interfaces#

Description: keep each domain web surface as the primary interface and use links between systems.

Pros:

  • Minimal central integration ownership.
  • Domains iterate independently.

Cons:

  • Breaks one-studio promise.
  • High cognitive overhead and context switching.
  • Weak traceability and inconsistent quality bars.

Option 2: Thin Studio Launcher#

Description: provide one Studio home that only launches domain tools.

Pros:

  • Fast initial delivery.
  • Low immediate UI complexity.

Cons:

  • Does not expose advanced capabilities in a unified operational model.
  • Cannot enforce parity, audit, or common approval patterns.

Option 3: Unified Studio IA with Capability-Exposure Contracts (Chosen)#

Description: implement OSHUN Studio as a single expert web application with shared IA primitives, domain capability exposure standards, and cross-domain contracts for context, actions, and observability.

Pros:

  • One coherent operational surface.
  • Enforceable parity and quality gates.
  • Strong cross-domain lineage and governance.

Cons:

  • Higher initial integration and governance complexity.
  • Requires disciplined domain adapter and contract management.

Decision Outcome#

Chosen option: Option 3 - Unified Studio IA with capability-exposure contracts.

IA Model (Normative)#

OSHUN Studio will use a layered IA model:

  1. Program Layer: portfolio/program control (Project Obsidian, etc.).
  2. Workspace Layer: team, domain, and project context switching.
  3. Capability Layer: domain modules (Yemaya, Isis, Hathor, Aja, Bellona).
  4. Workflow Layer: end-to-end operational flows across domains.
  5. Artifact Layer: files, assets, outputs, models, builds, and reports.
  6. Governance Layer: approvals, audit trail, policy and compliance evidence.

Studio Top-Level Navigation (Normative)#

The primary IA must expose these top-level surfaces:

  • Studio Home
  • Programs
  • Projects
  • Assets
  • Generation
  • World & Narrative
  • Motion
  • Build & Runtime
  • Review & Approvals
  • Observability
  • Governance

Capability Exposure Standard (Normative)#

For each advanced capability mapped from domain docs, Studio must expose:

  • discoverability entry point
  • primary workflow (create/execute)
  • monitoring/status visibility
  • failure diagnostics and recovery actions
  • collaboration and approvals
  • audit and telemetry events

No capability is considered exposed unless all six exposure criteria are implemented.

Context Model (Normative)#

All studio operations must be contextualized by:

  • programId
  • projectId
  • workspaceId
  • domain
  • capability
  • actorId
  • requestId / traceId

This context must persist in route state, API calls, events, and audit records.

Architecture Implications#

  • apps/oshun/web becomes the canonical Studio shell for expert workflows.
  • Domain APIs remain source-of-truth for domain-owned operations.
  • Studio adapters normalize domain operations into shared workflow and artifact semantics.
  • Shared IA components in libs/oshun/ui and route contracts in libs/oshun/navigation become mandatory for Studio surfaces.

Acceptance Criteria (OST-00001)#

OST-00001 is complete only when all criteria below are true:

  1. ADR published at docs/adr/ADR-0019-oshun-studio-information-architecture.md.
  2. ADR defines explicit IA layers and top-level Studio navigation surfaces.
  3. ADR defines capability-exposure standard with objective completion rules.
  4. ADR defines context model required across routes, APIs, events, and audit.
  5. ADR aligns with existing OSHUN ADRs (ADR-0007 through ADR-0012) without conflict.
  6. ADR names the five Studio domains (Yemaya, Isis, Hathor, Aja, Bellona) and Project Obsidian as governing production scope.
  7. ADR includes measurable quality and governance implications for implementation.

Consequences#

Positive Consequences#

  • One stable IA contract for Studio-scale execution.
  • Clear definition of what it means to fully expose a domain capability.
  • Reduced UX drift and improved cross-domain operational cohesion.

Negative Consequences#

  • Requires stronger integration discipline across domain teams.
  • Adds governance overhead for changes that affect shared IA contracts.

Risks and Mitigations#

Risk Probability Impact Mitigation
Capability exposure drift over time Medium High Add parity checks between docs, API resources, and UI routes in CI
Over-complex top-level nav for new users Medium Medium Role-based default layouts + progressive disclosure
Cross-domain context loss in long workflows Medium High Enforce context contract in route and API middleware
Operational overload from dense interfaces Medium Medium Keyboard-first UX, command palette, saved views, adaptive dashboards

Monitoring and Observability Requirements#

Track at minimum:

  • route-level capability usage and abandonment
  • time-to-first-success per capability workflow
  • failure rates by domain capability
  • approval cycle times and rollback rates
  • cross-domain handoff latency
  • docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md
  • docs/adr/ADR-0014-oshun-web-and-pwa-strategy.md
  • docs/adr/ADR-0015-deep-linking-and-cross-domain-routing.md
  • docs/adr/ADR-0016-shared-identity-and-cross-domain-session-model.md
  • docs/adr/ADR-0017-offline-caching-and-sync-strategy.md
  • docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md

References#

  • docs/domains/yemaya/features.md
  • docs/domains/isis/features.md
  • docs/domains/hathor/features.md
  • docs/domains/aja/features.md
  • docs/domains/bellona/features.md
  • docs/domains/yemaya/api/README.md
  • docs/domains/isis/api/README.md
  • docs/domains/hathor/api/README.md
  • docs/domains/aja/api/README.md
  • docs/domains/bellona/api/README.md
  • TODOS.md (Phase 27: Project Obsidian)