Disciplines · Decisions (ADRs)

ADR-0057: OSHUN Customer/Admin Shell Relationship Model

ADR-0055 and ADR-0056 now define the customer shell relationships for web and mobile.

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, Operations, Trust and Safety, Governance leads
Supersedes: N/A
Superseded by: N/A

Context and Problem Statement#

ADR-0055 and ADR-0056 now define the customer shell relationships for web and mobile. The remaining structural ambiguity was above that layer: the PRD says OSHUN has one customer shell and one admin shell, but the implementation still blurred them together.

In practice, /studio routes existed, but they were rendered inside customer shell chrome and even surfaced from customer Explore as if Studio were simply another discovery destination.

That ambiguity created several risks:

  • customer navigation implied that operator tooling was part of ordinary member wayfinding
  • admin routes inherited customer chrome, assistant entry, and customer shell expectations they do not actually satisfy
  • the product lacked one explicit rule for how account/session continuity, evidence continuity, and shell separation should coexist
  • future admin and customer IA work had no authoritative shared contract to reference

The PRD already states the intended end-state:

  • customer and admin are one platform, not isolated products
  • admin web is the canonical operator cockpit
  • admin mobile is the urgent operations companion
  • review, moderation, support, privacy, persona ops, model ops, and incidents must unify under one admin shell and one shared evidence model

Decision Drivers#

  • Boundary clarity: customer and admin must be connected without being flattened into one nav.
  • Role fit: member continuity and operator cockpit work have different jobs, density, and wayfinding needs.
  • Shared foundation: account, identity, entitlements, notifications, evidence lineage, and audit context must carry across shells.
  • Governed handoff: cross-shell transitions should be explicit, role-sensitive, and context-preserving.
  • Implementation leverage: the current web app needs a shell-separation seam that can upgrade many Studio pages at once.

Considered Options#

Option 1: Keep Studio inside the customer shell#

Description: continue rendering /studio inside customer shell nav and customer overlays.

Pros:

  • Lowest short-term implementation cost.

Cons:

  • Violates the PRD's separate-shell model.
  • Makes operator work look like ordinary customer discovery.
  • Prevents admin chrome, admin orientation, and role-appropriate controls from becoming explicit.

Option 2: Fork Studio into a fully separate app immediately#

Description: move admin routes into a totally separate deployed app before defining the shared contract.

Pros:

  • Hard physical separation.

Cons:

  • Over-rotates on deployment shape before the shared product contract is clear.
  • Does not answer how identity, context, evidence, and handoff should behave.
  • Adds migration cost before the shell relationship itself is modeled.

Option 3: Keep one platform app surface for now, but define two explicit shells with governed handoffs (Chosen)#

Description: publish one shared customer/admin shell contract, keep the web implementation in the same codebase, but make /studio render distinct admin shell chrome and require explicit operator handoff from the customer shell.

Pros:

  • Matches the PRD's one-platform / two-shell model.
  • Lets current /studio routes become a real admin shell immediately.
  • Preserves shared identity and evidence continuity without flattening nav.
  • Creates a reusable contract for docs, QA, and future admin-mobile work.

Cons:

  • Requires deliberate documentation so "same app codebase" is not mistaken for "same shell".
  • Leaves later admin-shell visual-thesis and deep information-design work for subsequent tasks.

Decision Outcome#

Chosen option: Option 3.

Normative Platform-Shell Rule#

OSHUN has two sibling shells inside one platform:

  • Customer Shell
  • Admin Shell

They share platform foundations, but they do not share primary navigation or surface semantics.

Shared-Foundation Rule#

Customer and admin share:

  • one account and session model
  • shared entitlements, notifications, and identity posture
  • shared object references, evidence lineage, and audit-linked context

Shared foundation does not mean shared nav chrome.

Customer-Shell Rule#

The customer shell is the member-facing continuity product across web and mobile. It owns contemplation, discovery, saved continuity, and member governance surfaces.

Customer navigation must not inline operator queues, governance workspaces, or Studio cockpit surfaces as if they were ordinary member destinations.

Admin-Shell Rule#

The admin shell is the operator cockpit. It owns queues, approvals, investigations, policy controls, evidence review, and operational reliability surfaces.

Admin routes must render dedicated operator wayfinding and context rather than inherit customer shell chrome.

Runtime-Fit Rule#

  • Customer web is the broad dashboard and deep workspace runtime for members.
  • Customer mobile is the continuity-first companion.
  • Admin web is the canonical operator cockpit.
  • Admin mobile is the urgent operations companion, not the parity target for the full cockpit.

Handoff Rule#

The normative cross-shell handoffs are:

  1. Customer -> Admin: explicit, role-gated operator access that preserves the relevant subject or artifact context and switches into admin navigation.
  2. Admin -> Customer: deliberate return or preview handoff that drops admin chrome while keeping only the minimal member-facing context.

Customer-Entry Rule#

Customer surfaces may advertise that operator tooling exists, but they should route access through a governed entry point such as profile/operator access, not embed admin workspace links into discovery content.

Contract Publication#

The shared shell-boundary model lives in libs/oshun/navigation/src/platform-shells.ts.

The current web admin-shell resolution and nav grouping live in apps/oshun/web/src/navigation/shells.ts.

Scope Boundaries#

  • This ADR defines the relationship between customer and admin shells.
  • It does not finish the full admin-shell redesign or visual-thesis work; later tasks such as V1-AWEB-093 still deepen that surface.
  • It does not define every admin mobile route; it only defines admin mobile as the urgent companion role in the shared shell model.

Architecture Implications#

  • /studio routes should render admin shell chrome rather than customer shell navigation.
  • customer Explore should stop presenting Studio as a peer discovery area
  • operator access should be exposed through an explicit customer-shell handoff surface
  • docs, tests, and route helpers should distinguish customer shell behavior from admin shell behavior

Acceptance Criteria#

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

  1. A canonical ADR defines the customer/admin shell relationship.
  2. Shared navigation code publishes the same platform-shell boundary model.
  3. The web implementation renders /studio inside explicit admin shell chrome.
  4. Customer surfaces no longer present Studio as ordinary discovery navigation.
  5. Operator access is exposed through an explicit customer-shell handoff.
  6. Tests verify customer/admin shell resolution and the governed handoff path.
  • docs/adr/ADR-0019-oshun-studio-information-architecture.md
  • docs/adr/ADR-0061-oshun-web-shell-relationship-model.md
  • docs/adr/ADR-0062-oshun-mobile-shell-relationship-model.md

References#

  • docs/releases/v1/specs/web-app-admin-v1-prd.md
  • libs/oshun/navigation/src/platform-shells.ts
  • apps/oshun/web/src/navigation/shells.ts
  • apps/oshun/web/src/components/ShellLayout.tsx