Admin Cockpit · Conventions

ADMIN_WALKTHROUGH — Oshun Admin (operator cockpit)

Conventions and reading guide for the Admin Cockpit walkthrough.

9sections3 minread1table
Markdown source
On this page

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/; 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#

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

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