Disciplines · Decisions (ADRs)

ADR-0021: OSHUN Studio Search and Global Discovery

Studio already contains cross-domain explore and search capabilities, plus a deterministic ranking strategy in the BFF.

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

Status: Accepted
Date: 2026-02-23
Authors: OSHUN Studio Product Design, OSHUN Web Engineering
Reviewers: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project Obsidian Program Design

Context and Problem Statement#

Studio already contains cross-domain explore and search capabilities, plus a deterministic ranking strategy in the BFF. However, advanced Studio workflows need a governed global discovery model that unifies search intent, contextual relevance, and actionability across domains.

Without an explicit search/discovery decision, Studio risks:

  • inconsistent search semantics across domains and surfaces
  • fragmented relevance behavior between ranking and UI presentation
  • weak context preservation when moving from discovery to execution
  • reduced trust in global results for high-stakes production workflows

Decision Drivers#

  • Relevance determinism: ranking behavior must be predictable and auditable.
  • Cross-domain discoverability: one query should support multi-domain outcomes with clear source context.
  • Actionability: results should transition users directly into workflows.
  • Context continuity: discovery-to-workflow handoff must preserve context.
  • Operational governance: search surfaces require policy, telemetry, and rollback-safe releases.

Considered Options#

Option 1: Domain-Specific Search Experiences#

Each domain maintains independent search and discovery behavior.

Pros:

  • Local optimization for domain-specific semantics.

Cons:

  • Cross-domain inconsistency and high operator context-switch cost.
  • Duplicate ranking and UX governance burden.

Option 2: Shared Endpoint, Ungoverned Discovery UX#

Use one backend search path while allowing ungoverned frontend discovery patterns.

Pros:

  • Faster UI iteration in the short term.

Cons:

  • Inconsistent result interpretation and action flows.
  • Weak guarantees for accessibility and policy-sensitive discovery actions.

Option 3: Unified Global Discovery System with Governed Search Semantics (Chosen)#

Adopt one global search and discovery model with deterministic ranking, context-preserving handoff, policy-aware action controls, and auditable release governance.

Pros:

  • Consistent, trustworthy discovery across all Studio domains.
  • Better operator efficiency and lower error rate in result-to-action paths.
  • Clear observability and governance for search quality.

Cons:

  • Increased governance overhead for discovery-surface changes.

Decision Outcome#

Chosen option: Option 3.

Search/discovery requirements:

  1. Canonical query contract: shared query semantics and filter behavior.
  2. Deterministic ranking model: explainable ordering and tie-break rules.
  3. Contextual result actions: each result maps to clear execution entrypoint.
  4. Cross-domain grouping: preserve domain identity while enabling blended discovery.
  5. Release governance: validate -> approve -> publish with telemetry/audit and rollback coverage.

Normative Rules#

Query Contract#

  • Governed discovery surfaces must support consistent query/filter semantics.
  • Empty-state discovery behavior must be deterministic and intentionally curated.

Ranking Contract#

  • Ranking formula and tie-break behavior must be documented and versioned.
  • Ranking changes must include before/after evidence and rollback strategy.

Result Action Contract#

  • Every result item must expose an explicit action path and preserved context.
  • Cross-domain actions must include deterministic return paths.

Accessibility Contract#

  • Search input, filters, and result actions must be keyboard-accessible.
  • Result grouping and metadata must be screen-reader interpretable.

Release Validity Contract#

A search/discovery release is valid only when all are true:

  • query and ranking behavior validations pass
  • action-path and context-preservation checks pass
  • accessibility checks pass
  • role-authorized approval exists
  • telemetry/audit records are complete
  • rollback reference is defined

Architecture Implications#

  • Global ranking strategy remains implemented and governed via BFF search contracts (apps/oshun/bff/src/search).
  • Discovery surfaces in apps/oshun/web must align to shared ranking and route contracts.
  • Route/context contracts remain aligned with libs/oshun/navigation.
  • Search/discovery observability remains centralized in libs/oshun/analytics.

Acceptance Criteria (OST-00065)#

OST-00065 is complete only when:

  1. ADR exists at docs/adr/ADR-0027-oshun-studio-search-and-global-discovery.md.
  2. ADR defines options, trade-offs, and selected strategy.
  3. ADR defines query, ranking, result-action, accessibility, and release-validity contracts.
  4. ADR aligns with ADR-0007 through ADR-0020.
  5. ADR aligns with docs/releases/v1/specs/search-ranking-strategy.md, docs/releases/v1/design/ux-principles.md, and libs/oshun/navigation.
  6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

Consequences#

Positive#

  • Higher trust and consistency in Studio discovery behavior.
  • Stronger cross-domain query-to-action workflow continuity.
  • Better quality governance for ranking and discovery changes.

Negative#

  • Additional validation overhead for search/discovery releases.
  • Requires coordinated ownership across BFF, Web, and Product Design.
  • 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

References#

  • docs/releases/v1/specs/search-ranking-strategy.md
  • docs/releases/v1/reports/metrics.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
  • apps/oshun/web/src/components/UniversalSearchPanel.tsx
  • apps/oshun/web/src/components/explore/ExploreDashboard.tsx
  • apps/oshun/bff/src/search/ranking.ts