# Oshun V1 Admin Information Architecture

> Authoritative IA for the admin web and admin mobile shells. Pairs with
> `docs/oshun/ia-and-experience-quality.md` (customer IA) and with the admin
> event taxonomy in `libs/oshun/analytics/src/admin-taxonomy.ts`.

## Shell premise

Admin surfaces are dense operational workspaces with:

- Compact queue states with explicit SLA timers.
- Hard audit trails — every decisive action emits a structured audit event and
  is recoverable from the audit pipeline.
- Scan-first hierarchy — tables, fixed action rails, filter chips, and
  decision-ready inspector panels.
- Strict RBAC: every workspace is gated by role and tenant scope per ADR-0006.
- Locale fallback to `en-US` for dense data while preserving locale for
  customer-visible content under review.

## Top-level workspaces

| Workspace          | Route                              | Primary roles                             | Purpose                                                              |
| ------------------ | ---------------------------------- | ----------------------------------------- | -------------------------------------------------------------------- |
| Inbox              | `/inbox`                           | every operator                            | Personal queue: assigned items across review/T&S/support/privacy     |
| Review             | `/review`                          | reviewer                                  | Editorial certification, source binding, publish gate, rollback      |
| Trust & Safety     | `/trust-safety`                    | T&S moderator                             | Moderation queue, voice abuse, persona disputes, appeals             |
| Personas           | `/personas`                        | T&S persona ops                           | Persona intake, evaluation, promotion, rollback                      |
| Models (Isis)      | `/models` and `/isis`              | model operator                            | Model and workflow intake, evaluation, promotion, kill-switch        |
| Editorial          | `/editorial`                       | reviewer                                  | Studio authoring queue, content readiness, locale gates              |
| Policy             | `/policy`                          | T&S lead                                  | Policy version inspection, rollout decisions                         |
| Incidents          | `/incidents`                       | reliability + incident commander          | Active incident bridge, runbook invocation, comms cadence            |
| Privacy            | `/privacy`                         | privacy operator                          | DSAR queue, consent, retention, residency, privacy-incident response |
| Rights             | `/rights`                          | rights operator                           | Rights agreements, watermark disputes, provenance disputes           |
| Support            | `/support`                         | support operator                          | Customer message-center cases, billing, refunds                      |
| Messaging          | `/messaging` and per-channel paths | messaging operator                        | Telegram channels, WhatsApp, email/SMS templates, compliance         |
| Research integrity | `/research-integrity`              | compliance + research lead                | Source-integrity audits, retraction cascade, benchmark integrity     |
| Tenant console     | `/tenant-console`                  | tenant administrator (per tenant)         | SSO, SCIM, OneRoster, role customization, audit explore              |
| Analytics          | `/analytics`                       | operator + analyst (read-only by default) | Dashboards, drill-down, export                                       |
| Handoff            | `/handoff`                         | release captain + launch support          | Launch-day war-room, canary monitoring, rollback recognition         |

Routes correspond to directories under `apps/oshun/admin/src/app/`. The route
tree is the structural source of truth; this document is the customer-facing
reference.

## Tenant console isolation

`/tenant-console` is strictly tenant-scoped. Tenant administrators operate
inside their tenant's data only — no cross-tenant visibility, no operator-class
privileges, no Oshun-admin queues. Tenant-console ownership lives in the tenant
administrator role; operator routes are inaccessible from the tenant console.

## Shared admin chrome

- **Header**: tenant + locale picker, identity + role chip, on-call status
  indicator, status-page link.
- **Left nav**: workspace switcher, grouped by operator class (reviewer / T&S /
  privacy / compliance / support / launch).
- **Action rail**: fixed on every workspace; primary actions (approve, reject,
  escalate, request changes, freeze) live here.
- **Inspector**: right-side drawer reveals the canonical record for the selected
  row — full audit history, related items, decision packet authoring.
- **Audit trail**: persistent surface at the bottom of every inspector; every
  decisive action emits an event and is reversible where policy permits.

## Inspector contracts

Every inspector renders these regions:

1. **Identity** — the canonical record, with tenant, scope, owner, creation
   context.
2. **Evidence** — source bundles, attachments, prior decisions, linked records.
3. **Decision** — structured form for the decision (class, reason code, action,
   comms template), with RBAC-gated submit.
4. **Audit** — the event history for the record (per `admin-taxonomy.ts`).
5. **Linked** — related records (other queues, other workspaces, prior
   incidents).

The contract is shared across queues so operators move between workspaces
without re-learning the UI.

## Decision and audit contract

- Every decisive action is structured: class, reason code, optional comms
  template, optional escalation. No free-text-only decisions on launch-critical
  paths.
- Reason codes are canonical per workspace and aligned with `admin-taxonomy.ts`.
- Every action emits an audit event with operator identity, scope, decision
  payload, and a reversible-or-not flag.
- Bulk actions are gated by per-class allowlists; bulk-action authorization
  requires a secondary co-sign for above-threshold actions.

## Dense-data ergonomics

- Tables: compact rows, fixed header, sticky action rail, in-row inspector
  expansion, keyboard navigation (j/k row movement, enter to open inspector, `.`
  to focus action rail).
- Filters: chips above the table; saved-filter library per operator;
  URL-shareable filter state.
- SLA timers: every queued item shows time-in-queue against the workspace's SLO;
  warning at 50%, breach at 100%.
- Bulk selection: shift-click range select, ctrl-click toggle; bulk-action
  authorization step shows the affected set.

## Notifications

- Web: in-app toast for assignments, comments, escalations; push-style alerts
  for incidents.
- Mobile: native push for urgent queues (T&S crisis, incidents, on-call);
  workspace-specific notification preferences.

## Mobile admin

`shell_admin_mobile` covers urgent operator paths only:

- Incident bridge: active incident summary, runbook references, comms cadence
  reminders.
- Crisis review: T&S crisis-tagged items with senior-reviewer routing.
- Privacy incident first-response: evidence preservation, freeze
  exports/deletions.
- Approval signoffs: model promotions, persona promotions, release gates.

Dense-data workspaces (review queues, analytics drill-down) stay on the web
shell.

## Accessibility minimums (admin)

- Keyboard navigation for every queue action and inspector control.
- Focus order matches reading order; visible focus rings on every control.
- Screen-reader landmarks per workspace region (header, nav, action rail,
  inspector, audit trail).
- Color is never the only conveyance — every chip and severity indicator carries
  text and an icon.
- Locale fallback to `en-US` for dense-data labels, with locale- preserved
  customer-visible content.

## Update authority

This document is updated when:

- A new top-level workspace is added.
- A workspace ownership row in the route tree changes.
- The inspector contract evolves (new region or new audit field).
- A new operator role is introduced under ADR-0006.

The platform UI lead and the admin product lead co-own this document. T&S lead,
privacy lead, and compliance lead co-review changes that affect their
workspaces.
