---
path: /analytics
surface: admin
domain: operations
auth: signed-in (admin) + scope:admin:workspace:analytics
source: apps/oshun/admin/src/app/analytics/page.tsx
status: drafted
last_walked: '—'
---

# Operations · Analytics and executive reporting

## Purpose

Surface review, moderation, privacy, model, and incident metrics to product
leadership and executive readiness reviews. `operatorPromise`: "Reports are
generated from canonical event and decision streams, not handcrafted dashboards,
so attribution is trustworthy."

## Entry points

- Sidebar item **"Analytics"** (AdminSidebar — operations group)
- Incidents → analytics handoff (`incidents → analytics` per
  `OSHUN_ADMIN_WORKSPACE_RELATIONSHIPS`) — "Incident closeout generates an
  analytics report."
- Models → analytics handoff (`models → analytics`) — "Model promotion publishes
  metrics that land in analytics executive reports."

## Layout regions

Inside `AdminShell`:

- `<WorkspaceEntryPoint workspaceId="analytics" ...>`
- When `detail.accessible`, nine panels:
  - `<ReadinessDashboardPanel readinessReports={snapshot.readinessReports}>`
  - `<ReleaseReadinessGoNoGoPanel readinessReports={snapshot.readinessReports}>`
  - `<AdminAuditLogExplorerPanel />`
  - `<AdminBulkOperationsPanel />`
  - `<AdminBulkExportsPanel />`
  - `<AdminDeveloperPortalPanel />`
  - `<AdminIntegrationsRegistryPanel />`
  - `<AdminNotificationTemplatesPanel />`
  - `<AdminCommunicationsPanel />`

Only two panels receive props from the snapshot
(`extractReadinessDashboardSnapshot(detailValue)` → `readinessReports`); the
other seven `Admin*Panel` components are self-contained (self-fetching or driven
by module-level data).

## States

- [ ] Anonymous → middleware redirect to
      `/unauthorized?reason=missing-session&returnTo=/analytics`
- [ ] Signed-in (admin) without `admin:*`, `admin:studio`, or
      `admin:workspace:analytics` → `WorkspaceEntryPoint` "Access not granted";
      the nine panels hidden
- [ ] Scope ok + BFF ok → all nine panels render. The two readiness panels share
      `snapshot.readinessReports`; the seven `Admin*Panel`s render their own UI
      regardless of the analytics workspace fetch
- [ ] Scope ok + BFF `workspace-unavailable` → entry-point "Workspace data
      unavailable"; panels hidden
- [ ] Per-panel loading / empty handled inside each child

## Interactions

Top-level interactive elements live inside each child panel:

- [ ] **ReadinessDashboardPanel** — readiness report tiles
- [ ] **ReleaseReadinessGoNoGoPanel** — go/no-go decision surface
- [ ] **AdminAuditLogExplorerPanel** — explorer over admin audit logs
      (self-fetching)
- [ ] **AdminBulkOperationsPanel** — bulk admin operations launcher
- [ ] **AdminBulkExportsPanel** — bulk export jobs
- [ ] **AdminDeveloperPortalPanel** — developer portal entry
- [ ] **AdminIntegrationsRegistryPanel** — integrations registry
- [ ] **AdminNotificationTemplatesPanel** — notification templates editor
- [ ] **AdminCommunicationsPanel** — communications composer

The page itself exposes no buttons / inputs.

## Data & contracts

- **Reads**: `loadWorkspaceDetail('analytics', session)` →
  `/v1/admin/workspaces/analytics`; only
  `extractReadinessDashboardSnapshot(detail.result.value)` is applied — yielding
  `readinessReports`. Other panels fetch themselves
- **Writes**: per panel (bulk operations launch, bulk export submit, template
  publish, communication send)
- **Realtime**: _None at page level._
- **Auth/role check**: middleware + page
  (`canEnterAdminWorkspace(scopes, 'analytics')` → required scopes
  `['admin:*', 'admin:studio', 'admin:workspace:analytics']`)

## Cross-references

- Shell: `shell/01-app-shell.md`, `shell/04-workspace-pattern.md`
- Workspace definition: `libs/oshun/navigation/src/admin-ia.ts` (`analytics` —
  `kind: 'analytics-console'`, `operatorRelationship: 'measure'`,
  `bffWorkspaceId: 'analytics'`)
- Handoff origins (`from → analytics`): `../safety/incidents.md`,
  `../content/models.md`
- Library: `apps/oshun/admin/src/lib/readiness-dashboard-detail.ts`
- Component sources: `ReadinessDashboardPanel.tsx`,
  `ReleaseReadinessGoNoGoPanel.tsx`, `AdminAuditLogExplorerPanel.tsx`,
  `AdminBulkOperationsPanel.tsx`, `AdminBulkExportsPanel.tsx`,
  `AdminDeveloperPortalPanel.tsx`, `AdminIntegrationsRegistryPanel.tsx`,
  `AdminNotificationTemplatesPanel.tsx`, `AdminCommunicationsPanel.tsx`

## Open questions / known gaps

- [ ] The seven self-contained `Admin*Panel` components arguably belong to
      multiple workspaces (audit log explorer is cross-cutting); document why
      they all land here under Analytics versus Operations more broadly
- [ ] Document each self-fetching panel's endpoint (`/api/admin/audit-log`,
      `/api/admin/bulk-exports`, `/api/admin/integrations`, etc.)
- [ ] Readiness reports are the only BFF-backed data on this page; verify
      expectation that the rest of the surfaces operate on their own data
      streams (no dependency on the analytics workspace snapshot)