Admin Cockpit · Conventions

Admin journeys

Conventions and reading guide for the Admin Cockpit walkthrough.

4sections3 minread5tables
Markdown source
On this page

End-to-end multi-workspace flows for the admin app. Per-view files verify each workspace individually; journeys catch the bugs that hide between workspaces — broken handoffs, scope-gating gaps, audit trails that miss a step.

Same shape as the V1 PWA's WALKTHROUGH/journeys/: # Journey: heading, no frontmatter, then Personas → Pre-conditions → Steps → Post-conditions → Failure modes → E2E coverage when automation exists → Per-view files touched → Cross-references → Open questions.

When to walk an admin journey#

  • Before an admin app release — walk the relevant journeys for workspaces whose code changed.
  • After a structural change — middleware refactor, session-cookie rotation, scope taxonomy change, BFF endpoint move.
  • When an operator reports a confusing flow — find the matching journey; the failure mode is probably already there.

Journey bucket map#

Auth and entry (1)#

Journey What it walks
privileged-handoff.md Customer (or anon) → /handoff → out-of-band token mint → admin session cookie set → land at returnTo. Also covers expired-session re-handoff and rate-limit edge.

Governance flows (1)#

Journey What it walks
review-cycle-admin.md /review queue → /review/[reviewId] detail → stage graph + copilot draft → Approve/Request changes/Reject → sealed decision in audit. High-risk approval + delegation paths.

Safety flows (2)#

Journey What it walks
incident-handling-admin.md Auto-INC fires → /inbox → /incidents detail → acknowledge / assign / runbook / customer comms → resolve → postmortem → audit. Handoffs to /policy, /trust-safety, /support.
trust-safety-voice-abuse-response.md Voice abuse alert → /trust-safety → /trust-safety/voice-abuse → revocation cascade preview → commit → consent ledger updates → take-downs → optional S1 incident escalation.

Content / persona flows (1)#

Journey What it walks
persona-release-cycle.md /personas add → voice consent verified at /rights → policy pack attested at /policy → submit to /review → approval → promote preview → staging → production. Cross-links to V1 PWA Tara surface and the LoRA training journey.

Isis ops flows (1)#

Journey What it walks
isis-lora-training-admin.md /isis/civitai-intake → rights check → /isis/comfy-nodes + /isis/workflow-editor → /isis/runpod-endpoints → /isis/lora-training → /isis/output-gallery → optional /isis/model-merging → submit to /review → promote in /models.

Cross-cutting findings worth surfacing#

Recorded as the journeys were drafted. Several depend on per-view sweep results — refer to ../matrix/coverage.md for the consolidated cross-cutting findings.

  1. The handoff back-channel is opaque. The privileged-handoff journey describes the visible UI but the token-mint step is out-of-band — flagged in open questions for every admin journey that depends on a fresh session.
  2. Audit-log writes are the universal stamp. Every admin journey ends with verifying entries in apps/oshun/bff/src/routes/admin-audit-log.ts. Event taxonomies (incident.*, review.*, trust-safety.*, persona.*, isis.*) are documented per journey.
  3. The dashboard is composed from workspace summaries. Operators landing at / see WorkspaceSummaryCards for every workspace they can access. The journey-relevant view is each individual workspace, but the dashboard's loadWorkspaceOverview is the first read the operator makes.
  4. Cross-workspace handoffs use listOshunAdminWorkspaceRelationships() — see WorkspaceEntryPoint's "Handoffs from here" block. Journeys reference these relationships explicitly.
  5. Lilith workspace (backendStatus: 'backend-pending') blocks any journey that needs Lilith-room observability — flagged in persona-release-cycle.md open questions.
  6. The V1 PWA has parallel operator surfaces. /operator/admin in the V1 PWA mirrors /inbox here. /operator/admin/isis/provenance is the provenance inspector that this admin app's Isis flows produce bundles for. Cross-links go in both directions.
  7. Rate limit is per-replica in-memory. A multi-replica deploy will limit per-replica, not globally. Flagged in privileged-handoff.md failure modes and shell/02-routing-layouts.md open questions.

Adding a new admin journey#

  1. Pick a flow that traverses ≥ 2 admin workspaces (or ≥ 1 admin workspace + the V1 PWA) and has clear pre- and post-conditions.
  2. Confirm every workspace it touches has a per-view file; if not, write those first.
  3. Copy privileged-handoff.md as a starting shape.
  4. Ground every step in real component / route / BFF endpoint names from the per-view files. Don't invent.
  5. Use ls to confirm every per-view link target exists before committing.
  6. Add the new entry to the bucket map above with a one-line summary.