Disciplines · Decisions (ADRs)

ADR-0055: OSHUN Web Shell Relationship Model

ADR-0053 established Tara as the customer center.

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

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

Context and Problem Statement#

ADR-0053 established Tara as the customer center. ADR-0054 made Nisaba a first-class companion domain. The remaining gap on web was structural: the PRD already required one library/save model and one assistant entry layer, but the implemented web shell still only had explicit primary routes for Home, Explore, Activity, and Profile.

That left the web shell in an ambiguous state:

  • library existed as scattered links, saved-state copy, and Nisaba subpaths, but not as a normative customer-shell surface
  • assistant existed as a floating panel, but without one explicit rule saying whether it is a peer page or a global layer
  • save and return flows had no canonical destination on web
  • future route, nav, and QA work could not point to one authoritative relationship model for the six named shell surfaces

The PRD already points to the intended answer:

  • web needs deep library and collection management
  • web needs an assistant dock with context carry-over
  • the shell must present one coherent relationship among home, explore, activity, library, assistant, and profile

Decision Drivers#

  • Clarity: route, nav, and QA work need one explicit definition of what each web shell surface is for.
  • Continuity: saved material and assistant context must have a durable home.
  • Non-flattening IA: not every named shell surface should become a peer page with the same job.
  • Web fit: web is the depth, research, dashboard, and workspace runtime, so library and assistant need web-native semantics.
  • Contractability: shared code and docs should publish the same model.

Considered Options#

Option 1: Treat library and assistant as additional peer top-level pages#

Description: add Library and Assistant as ordinary peer shell routes beside Home, Explore, Activity, and Profile.

Pros:

  • Simple mental model for route lists.
  • Easy to mirror in nav code.

Cons:

  • Misstates assistant behavior on web, which is supposed to carry context from anywhere.
  • Encourages a flat shell where every surface competes equally.
  • Fails to distinguish structural destinations from global help layers.

Option 2: Keep library and assistant implicit#

Description: continue using saved-state links, local buttons, and the existing assistant panel without a formal shell rule.

Pros:

  • Lowest immediate implementation effort.
  • Avoids route and nav changes.

Cons:

  • Leaves the PRD requirements only partially implemented.
  • Makes save and continuity behavior inconsistent across surfaces.
  • Prevents shared IA code and docs from naming the actual web-shell model.

Option 3: Make library a structural shell surface and assistant a global continuity layer (Chosen)#

Description: declare Home, Explore, Activity, Library, and Profile as the structural web-shell surfaces, while Assistant remains a global entry layer that overlays those structural surfaces and carries context across them.

Pros:

  • Matches the PRD's "one library and save model" and "one assistant entry layer" language.
  • Gives saved-state and collection management a canonical web destination.
  • Preserves assistant as contextual help rather than a competing page.
  • Produces a reusable contract for web nav, docs, and QA.

Cons:

  • Requires explicit documentation so assistant is not mistaken for a missing route.
  • Requires shell navigation work to incorporate Library without flattening the Tara-centered model.

Decision Outcome#

Chosen option: Option 3.

Normative Web-Shell Rule#

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

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

Structural-Surface Rule#

On web, Home, Explore, Activity, Library, and Profile are structural destinations. They may appear in route contracts, shell navigation, and primary wayfinding.

Library Rule#

Library is the canonical web surface for saved, queued, highlighted, collected, and preserved cross-domain objects. Discovery may create saves and activity may reference them, but durable saved-state management belongs in Library.

Assistant Rule#

Assistant is not a peer structural route on web. It is the global assistant entry layer. It must inherit the current surface context, help the user act or decide, and then hand them back into the correct structural or domain destination.

Handoff Rule#

The core web-shell handoffs are:

  1. Home -> Explore when centered intent branches into discovery.
  2. Home -> Activity when the user should review or continue in-flight work.
  3. Explore -> Library when promising material becomes worth saving.
  4. Activity -> Library when reflected continuity needs a durable return point.
  5. Library -> Explore when saved context seeds fresh discovery.
  6. Library -> Activity when a saved object becomes the next active step.
  7. Assistant -> any structural surface when contextual help should resolve into an actual destination rather than linger as detached chat.

Contract Publication#

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

The web route publication for the structural surfaces lives in apps/oshun/web/src/navigation/routes.ts.

Scope Boundaries#

  • This ADR is web-only. Mobile-specific relationship work remains V1-UX-004.
  • This ADR does not define the customer/admin shell relationship; that remains V1-UX-005.
  • This ADR does not require the final assistant dock architecture or long-lived persistent dock state. That deeper web implementation remains later work such as V1-WEB-003.

Architecture Implications#

  • The web shell must expose a real /library route and corresponding shell-nav entry.
  • Saved-state affordances should route into Library when the user needs a durable return point.
  • Assistant triggers should work from any structural surface and should preserve surface context.
  • Web QA and accessibility shortcuts can now distinguish structural navigation from assistant invocation.

Acceptance Criteria#

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

  1. A canonical ADR defines the web relationship among home, explore, activity, library, assistant, and profile.
  2. Shared IA code publishes the same web-shell model.
  3. The web route contract exposes library as a shell surface.
  4. The assistant is explicitly modeled as a global entry layer rather than a missing peer page.
  5. Web docs and QA artifacts no longer describe the shell as only Home/Explore/Activity/Profile.
  • 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-0015-deep-linking-and-cross-domain-routing.md

References#

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