Disciplines · Decisions (ADRs)

ADR-0056: OSHUN Mobile Shell Relationship Model

The PRD already required the mobile app to support home, explore,

Accepted · 2026-03-24
9sections5 minread
Markdown source
On this page

Status: Accepted
Date: 2026-03-24
Authors: OSHUN Product, OSHUN Design, OSHUN Mobile Engineering
Reviewers: Tara, Arete, Veritas, Nyx, Nisaba leads
Supersedes: N/A
Superseded by: N/A

Context and Problem Statement#

The PRD already required the mobile app to support home, explore, activity, library, assistant, and profile, but the implemented mobile shell still exposed only four structural tabs:

  • home
  • explore
  • activity
  • profile

That left two major gaps:

  • library existed as shared saved-state infrastructure and an embedded view inside Explore, but not as a canonical mobile shell surface
  • assistant did not exist as a first-class mobile continuity layer at all

This created ambiguity in the most interruption-prone runtime:

  • saved material had no dedicated mobile return point
  • explore was carrying both discovery and preservation responsibilities
  • there was no global mobile assistant entry with contextual carry-over
  • docs, QA, and route contracts could not point to one explicit mobile relationship model

The PRD already points to the intended outcome:

  • the mobile app must support home, explore, activity, library, assistant, and profile
  • the customer shell must provide one library/save model and one assistant entry layer
  • assistant interaction should work anywhere in the app

Decision Drivers#

  • Continuity under interruption: mobile needs a durable preserve surface for small-session, stop-start behavior.
  • Thumb-reachable clarity: the shell should not hide saved-state management inside Explore.
  • Non-flattening IA: assistant should remain contextual help, not a sixth peer tab competing with structural destinations.
  • Cross-platform coherence: web and mobile should publish the same conceptual relationship while keeping platform-appropriate behavior.
  • Contractability: shared IA, routes, docs, analytics, and QA need one explicit mobile model.

Considered Options#

Option 1: Keep mobile at four tabs and leave library inside Explore#

Pros:

  • Lowest implementation cost.
  • Avoids tab-bar changes.

Cons:

  • Leaves the PRD only partially implemented.
  • Collapses discovery and preservation into one surface.
  • Makes saved-state return paths inconsistent on the platform that needs them most.

Option 2: Add both Library and Assistant as peer tabs#

Pros:

  • Simple mental model for tab inventory.
  • Easy to expose both capabilities in visible chrome.

Cons:

  • Misstates assistant behavior, which should inherit context from anywhere.
  • Produces a crowded mobile tab bar.
  • Treats assistant as a destination instead of a continuity layer.

Option 3: Make Library a structural tab and Assistant a global continuity sheet (Chosen)#

Pros:

  • Matches the PRD's "one library and save model" and "one assistant entry layer" language.
  • Gives mobile saved-state behavior a real shell home.
  • Preserves assistant as context-carrying help instead of a competing tab.
  • Produces one reusable model for IA, routes, telemetry, docs, and QA.

Cons:

  • Requires refactoring Explore to hand preserved material into Library instead of containing the full library view.
  • Requires explicit documentation so Assistant is not mistaken for a missing route.

Decision Outcome#

Chosen option: Option 3.

Normative Mobile-Shell Rule#

The mobile customer shell has five structural tab surfaces and one global continuity layer:

  • Home anchors
  • Explore branches
  • Activity reflects
  • Library preserves
  • Profile governs
  • Assistant guides as a global sheet

Structural-Tab Rule#

On mobile, Home, Explore, Activity, Library, and Profile are the structural shell tabs. They may appear in the tab bar, route contracts, and primary wayfinding.

Library Rule#

Library is the canonical mobile surface for saved, queued, highlighted, downloaded, and preserved cross-domain material. Explore may preview recent saves, but durable saved-state management belongs in Library.

Assistant Rule#

Assistant is not a peer mobile tab. It is the global mobile assistant continuity layer. It should open as a contextual sheet from anywhere in the app, inherit the current shell or domain context, and route the user back into the correct structural tab or domain destination.

Handoff Rule#

The core mobile-shell handoffs are:

  1. Home -> Explore when centered intent branches into discovery.
  2. Home -> Activity when the user wants quick continuity review.
  3. Explore -> Library when promising material becomes worth preserving.
  4. Activity -> Library when reflected continuity needs a durable return point.
  5. Library -> Activity when saved material becomes the next active step.
  6. Library -> Explore when preserved context should seed fresh discovery.
  7. Assistant -> any structural tab when contextual help should resolve into a real destination.

Contract Publication#

The shared representation of this rule lives in libs/oshun/navigation/src/customer-ia.ts.

The mobile route publication for structural tabs lives in apps/oshun/mobile/src/navigation/routes.ts.

Scope Boundaries#

  • This ADR is mobile-only. Web relationship work is defined in ADR-0055.
  • This ADR does not define the customer/admin shell relationship; that remains V1-UX-005.
  • This ADR does not require the final production assistant backend or streaming architecture. It defines the mobile shell relationship and entry behavior.

Architecture Implications#

  • The mobile shell must expose a real Library tab route.
  • Explore should preview saves and hand preserved context into Library instead of acting as the full library surface.
  • Assistant must be mounted at the mobile app root so it can open from shell tabs and domain routes alike.
  • Mobile telemetry, deep-link hydration, and smoke coverage should understand library as a structural tab.

Acceptance Criteria#

V1-UX-004 is complete only when all criteria below are true:

  1. A canonical ADR defines the mobile relationship among home, explore, activity, library, assistant, and profile.
  2. Shared IA code publishes the same mobile-shell model.
  3. The mobile route contract exposes library as a structural tab route.
  4. The mobile shell exposes a real library surface instead of only an embedded Explore section.
  5. The mobile app exposes assistant as a global continuity layer rather than a peer tab.
  6. Mobile docs and QA artifacts no longer describe the shell as only four tabs.
  • docs/adr/ADR-0059-oshun-customer-information-architecture-and-tara-centered-spine.md
  • docs/adr/ADR-0060-oshun-nisaba-first-class-customer-domain.md
  • docs/adr/ADR-0061-oshun-web-shell-relationship-model.md

References#

  • docs/releases/v1/specs/web-app-admin-v1-prd.md
  • apps/oshun/mobile/README.md
  • libs/oshun/navigation/src/customer-ia.ts
  • apps/oshun/mobile/src/navigation/routes.ts