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 inlibs/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-USfor 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:
- Identity — the canonical record, with tenant, scope, owner, creation context.
- Evidence — source bundles, attachments, prior decisions, linked records.
- Decision — structured form for the decision (class, reason code, action, comms template), with RBAC-gated submit.
- Audit — the event history for the record (per
admin-taxonomy.ts). - 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-USfor 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.