Eve library

Oshun V1 Admin Information Architecture

Guide

Revision 1

On this page

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.