# ADMIN_WALKTHROUGH — Oshun Admin (operator cockpit)

A granular, checklist-driven inventory of every view and interaction in the
Oshun Admin app — the operator cockpit served from `apps/oshun/admin`. Parallel
to the V1 PWA walkthrough at [`../WALKTHROUGH/`](../WALKTHROUGH/README.md); same
file format, different app.

## What this is (and is not)

- **Is**: A per-view checklist for every page in the admin app, plus shell docs
  (layout, middleware, auth, workspace pattern) and six end-to-end journeys.
- **Is not**: A duplicate of `WALKTHROUGH/`. The V1 PWA and the admin app are
  separate Next.js applications with separate layouts, middleware, auth cookies,
  and IA. Findings from one don't apply one-to-one to the other.

## Surface map

The admin app is a single Next.js workspace at `apps/oshun/admin` with 34
routes. There's no PWA manifest, no service worker, and no multi-domain shell —
it's an operator-only single-purpose product.

| Group             | Routes | Folder                                |
| ----------------- | ------ | ------------------------------------- |
| **Governance**    | 5      | `workspaces/governance/`              |
| **Safety**        | 7      | `workspaces/safety/`                  |
| **Content**       | 4      | `workspaces/content/`                 |
| **Operations**    | 5      | `workspaces/operations/`              |
| **Isis ops**      | 8      | `isis/`                               |
| **Cross-product** | 2      | `cross-product/`                      |
| **Meta**          | 3      | `meta/` (handoff, unauthorized, test) |

Operations now includes `/crashes`; Safety includes `/egbe` and
`/trust-safety/maya-anticheat` in addition to the original workspace routes.

Group taxonomy is derived from `OSHUN_ADMIN_WORKSPACE_MODEL` in
`libs/oshun/navigation/src/admin-ia.ts` — `group` field on each workspace
definition.

## Folder layout

```
ADMIN_WALKTHROUGH/
  README.md                # this file
  00-conventions.md        # references parent conventions; admin-specific notes
  shell/
    01-app-shell.md        # AdminShell, root layout, error/loading/not-found
    02-routing-layouts.md  # middleware, route groups, public paths, rate limit
    03-auth-session.md     # OSHUN_ADMIN_SESSION_COOKIE, scopes, handoff
    04-workspace-pattern.md # WorkspaceEntryPoint, loadWorkspaceDetail, BFF
  workspaces/
    governance/  safety/  content/  operations/
  isis/                    # /isis/* — 8 routes
  cross-product/           # /messaging/*, /tenant-console/*
  meta/                    # /handoff, /unauthorized, /__test/*
  matrix/
    routes.csv             # full route inventory with status
    coverage.md            # narrative + cross-cutting findings
  journeys/                # end-to-end multi-view flows
    README.md              # bucket map
```

## How to read a per-view file

Same as the V1 PWA walkthrough — see [`00-conventions.md`](./00-conventions.md).
YAML frontmatter at the top, then Purpose, Entry points, Layout regions, States,
Interactions, Data & contracts, Cross-references, Open questions. Every `- [ ]`
is a verifiable check.

Status of any single file:

- **stub** — file exists with header only
- **drafted** — content from code reading; not verified live
- **walked** — direct runtime evidence (manual or automated) verifies the
  reachable checks, with method and date recorded
- **stale** — code drifted since last walk

## The admin shell

Every workspace inherits the same chrome via `AdminShell`:

- **Sidebar** — `AdminSidebar`; lists workspaces grouped per
  `OSHUN_ADMIN_WORKSPACE_MODEL.group`
- **Header** — `AdminHeader`; operator label, density toggle, assistant
  invocation entry, command palette trigger
- **Main column** — workspace body, mounted at `<main id="admin-main">`
- **Skip link** — `Skip to main content` jumps to `#admin-main`
- **Command palette** — `AdminCommandPaletteProvider`; opens via shortcut from
  `@oshun/shell-assistant/invocation-points`
- **Assistant panel** — `AdminAssistantPanel`; guarded by
  `evaluateAssistantInvocationGuard` with scopes + entitlements
- **Breadcrumb context** — `AdminBreadcrumbProvider`
- **Density** — `useAdminDensity` toggles `data-admin-density` on `<html>`

See [`shell/01-app-shell.md`](./shell/01-app-shell.md) for the full walkthrough
of `AdminShell`.

## The workspace pattern

Every admin page that requires a session follows the same shape:

1. Server component calls `getAdminServerSession()`; redirects to
   `/unauthorized` with reason + returnTo if no session
2. Loads workspace data via `loadWorkspaceDetail(workspaceId, session)` (BFF
   call) and `fetchAdminOperatorView(session)`
3. Renders `<AdminShell>` with the workspace id
4. Inside the shell, renders a workspace-specific panel (`<UnifiedInboxPanel>`,
   `<ReviewQueue>`, etc.) or falls back to `<WorkspaceEntryPoint>` when data is
   unavailable

See [`shell/04-workspace-pattern.md`](./shell/04-workspace-pattern.md).

## Reading order

- **New operator** — start at `shell/03-auth-session.md` to understand the
  handoff flow, then walk `workspaces/governance/dashboard.md`.
- **Reviewing a workspace change** — open `matrix/routes.csv`, filter by the
  prefix you touched, walk those files.
- **Pre-release sweep** — walk journeys in `journeys/` first to catch the
  cross-workspace failure modes the per-view files miss.

## Source of truth

- Workspace definitions: `libs/oshun/navigation/src/admin-ia.ts`
  (`OSHUN_ADMIN_WORKSPACE_MODEL`)
- Auth contract: `apps/oshun/admin/src/lib/session-cookie.ts` and
  `apps/oshun/admin/src/lib/server-session.ts`
- BFF client: `apps/oshun/admin/src/lib/bff-client.ts` and
  `apps/oshun/admin/src/lib/workspace-loader.ts`
- AdminShell: `apps/oshun/admin/src/components/AdminShell.tsx`

## Relationship to the V1 PWA walkthrough

The V1 PWA's `/operator/*` routes documented from the
[`operator overview`](../WALKTHROUGH/operator/operator-overview.md) are
**separate** from this admin app. The V1 PWA's operator routes are
operator-level views inside the consumer app shell. The admin app here is a
dedicated operator-only Next.js app with its own deployment, auth flow, and
shell. Both can exist; they serve different audiences and have different threat
models.