# ADR-0057: OSHUN Customer/Admin Shell Relationship Model

**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.

## Related Decisions

- `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`