Disciplines · Decisions (ADRs)

ADR-0022: OSHUN Studio Cross-Domain Entity Model

Studio workflows now span navigation, discovery, orchestration, and governance across multiple domains.

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

Context and Problem Statement#

Studio workflows now span navigation, discovery, orchestration, and governance across multiple domains. Those workflows increasingly depend on shared entity references (content, workflows, assets, builds, timelines, reports) that must resolve reliably across domain boundaries.

Without an explicit cross-domain entity model, Studio risks:

  • inconsistent entity identity semantics across services and surfaces
  • fragile deep-link and result-action references
  • duplicate or conflicting entity metadata across domains
  • poor traceability in audit, telemetry, and incident workflows

Decision Drivers#

  • Entity identity consistency: one normalized model for cross-domain references.
  • Interoperability: shared entity contracts across BFF, web, and domain adapters.
  • Actionability: entity references must map deterministically to routes and actions.
  • Observability: entity operations must be auditable and traceable.
  • Governance safety: schema evolution requires compatibility and rollback controls.

Considered Options#

Option 1: Domain-Owned Entity Models Only#

Each domain defines independent entity IDs and metadata contracts.

Pros:

  • Local domain autonomy.

Cons:

  • High integration complexity and inconsistent cross-domain behavior.
  • Difficult audit and lineage tracking.

Option 2: Shared Mapping Layer Over Independent IDs#

Keep domain IDs, add a lightweight translation layer for cross-domain features.

Pros:

  • Lower migration cost initially.

Cons:

  • Mapping drift and ambiguity over time.
  • Harder to guarantee deterministic routing and analytics consistency.

Option 3: Unified Cross-Domain Entity Model with Governed Contracts (Chosen)#

Adopt one canonical cross-domain entity envelope with domain-specific extensions and versioned compatibility governance.

Pros:

  • Deterministic entity references across Studio workflows.
  • Stronger lineage, observability, and compliance posture.
  • Lower long-term integration complexity.

Cons:

  • Requires stricter schema governance and migration discipline.

Decision Outcome#

Chosen option: Option 3.

Cross-domain entity model requirements:

  1. Canonical entity envelope with stable identity and domain origin.
  2. Typed domain extensions for domain-specific metadata.
  3. Deterministic action mapping from entity -> route/action contract.
  4. Versioned compatibility rules with forward/backward checks.
  5. Release governance with validation, approval, telemetry/audit, and rollback.

Normative Rules#

Identity Contract#

  • Every cross-domain entity must expose a globally stable entityId.
  • Entity IDs must be immutable once published.
  • Entity envelope must include authoritative domain origin.

Metadata Contract#

  • Common fields (title, summary, status, timestamps, ownership) are required.
  • Domain-specific extensions must be namespaced and versioned.

Action-Mapping Contract#

  • Each entity type must map to deterministic route/action entrypoints.
  • Fallback behavior must be defined for unavailable entity targets.

Compatibility Contract#

  • Schema changes require compatibility checks and explicit version bumps.
  • Breaking changes must include migration plan and rollback references.

Release Validity Contract#

A cross-domain entity-model release is valid only when all are true:

  • identity and schema validation checks pass
  • route/action mapping checks pass
  • compatibility regression checks pass
  • role-authorized approval exists
  • telemetry/audit records are complete
  • rollback strategy is documented

Architecture Implications#

  • Domain metadata authority remains in libs/oshun/domain-registry for domain descriptors.
  • Cross-domain entity contracts are enforced at BFF aggregation and web consumption boundaries.
  • Navigation/action mappings remain aligned with libs/oshun/navigation.
  • Entity lifecycle observability remains centralized in libs/oshun/analytics.

Acceptance Criteria (OST-00073)#

OST-00073 is complete only when:

  1. ADR exists at docs/adr/ADR-0028-oshun-studio-cross-domain-entity-model.md.
  2. ADR defines options, trade-offs, and selected strategy.
  3. ADR defines identity, metadata, action-mapping, compatibility, and release-validity contracts.
  4. ADR aligns with ADR-0007 through ADR-0021.
  5. ADR aligns with docs/releases/v1/design/ux-principles.md, libs/oshun/domain-registry, and libs/oshun/navigation.
  6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

Consequences#

Positive#

  • Reliable cross-domain entity references and better workflow continuity.
  • Stronger audit/compliance traceability for entity-driven operations.
  • Better long-term platform interoperability and maintainability.

Negative#

  • Higher upfront schema-governance and migration effort.
  • Requires coordinated adoption across domain adapters.
  • 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
  • docs/adr/ADR-0019-oshun-studio-information-architecture.md
  • docs/adr/ADR-0020-oshun-studio-design-language-and-visual-identity.md
  • docs/adr/ADR-0021-oshun-studio-typography-system.md
  • docs/adr/ADR-0022-oshun-studio-color-system-and-token-governance.md
  • docs/adr/ADR-0023-oshun-studio-spacing-and-layout-grid.md
  • docs/adr/ADR-0024-oshun-studio-component-primitives-and-composition-contracts.md
  • docs/adr/ADR-0025-oshun-studio-complex-interaction-patterns-and-state-orchestration.md
  • docs/adr/ADR-0026-oshun-studio-navigation-and-command-surfaces.md
  • docs/adr/ADR-0027-oshun-studio-search-and-global-discovery.md

References#

  • libs/oshun/domain-registry/src/index.ts
  • apps/oshun/web/src/navigation/routes.ts
  • docs/releases/v1/specs/studio-domain-dependency-and-data-contract-map.md
  • docs/releases/v1/design/ux-principles.md
  • 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