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

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

## Related Decisions

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