Org Admin Console UI (Phase 14 — TASK-0133)
The interaction contract for the org admin console in
apps/web: the tabbed console gated by the org-admin role, the audit viewer with CSV export, the org policy editor, and the retention runs. The API contract lives in ../api/org-admin.md (authoritative). Component map:
app/org/[orgId]/admin/page.tsx— the console shell: sticky tab bar (8 tabs,?tab=deep-linking), the 403 role-gate panel, and the workspace picker (lifted, shared by the two workspace-scoped tabs)components/admin/org-admin/OverviewTab.tsx— counts, 30-day storage/audit trends, the effective-policy cardcomponents/admin/org-admin/MembersTab.tsx— the member table (search, role, suspend round-trip via a confirm dialog)components/admin/org-admin/PoliciesTab.tsx— the five enforcement points (toggles + the file-size + session-lifetime inputs)components/admin/org-admin/RetentionTab.tsx— per-scope policy editor + Run-now cards (dry/execute) + the run reportcomponents/admin/org-admin/AuditTab.tsx— the filterable viewer + export (sync download / async status + single-use URL)components/admin/org-admin/ApiKeysTab.tsx/WebhooksTab.tsx— wrap the existing per-workspace settings panels around the pickercomponents/admin/org-admin/WorkspacePicker.tsx— the org's workspaces (the picker for the two workspace-scoped tabs)app/(app)/w/[workspace]/page/[id]/share/page.tsx— the share page shows thedisableGuestPublicSharenotice (the server is the enforcement; the notice is UX only)lib/org-admin.ts— the admin API client (incl. the sync/async export union viaapiFetchRaw)
1. The console shell & the role gate
The console is at /org/{orgId}/admin (tab deep-linkable as
?tab=overview|members|integrations|policies|retention|api-keys|webhooks| audit). The sticky tab bar renders the eight tabs as buttons
(aria-current marks the active one).
The gate (the only authorization surface). The console is read-
gated by GET /orgs/:orgId/admin/workspaces (the workspace picker's
data). If that returns 403 { reason: "requires_org_admin" } — the
caller is a MEMBER/GUEST, a non-member, or a member of ANOTHER org (the
reason is the same for all three, so cross-org is never distinguishable)
— the shell renders the gate panel and NO tabs load:
You need org-admin rights to open this console. Ask the organization owner to grant you the ADMIN role.
A MEMBER reaching the console (e.g. via the SSO JIT-provisioned login)
sees exactly this. There is no partial access: every tab's data comes
from an admin route, all of which are requireOrgAdmin-gated.
Loading / empty. Each tab independently shows its own loading state (skeleton) and empty state (e.g. "No members yet", "No audit rows match"). The workspace picker shows an inline error + retry if the org's workspaces fetch fails for a reason other than 403.
Mobile / a11y. The tab bar is horizontally scrollable on narrow
viewports (the grids collapse to one column). The confirm dialogs are
role="dialog" with a labelled title; the toggles are role="switch"
with a visible label; the stat values pair a label div with a value div
(screen-reader caption provided).
2. Overview tab
Cards for member count (with the active-30d subcount), workspaces, pages, databases, files, and storage bytes — plus the two 30-day trend rows (storage, audit). The effective policy card shows the five enforcement points as read-only values (it is a mirror; the edit surface is the Policies tab).
3. Members tab
A table of the org's members: name, email, role, status, last login,
last active, joined. Search (?q=) filters by name/email.
- Role change — a select per row (ADMIN / MEMBER / GUEST). Sending
OWNERis rejected by the API (ownership_transfer_required); demoting the last owner is rejected (last_org_owner). - Suspend / unsuspend — a row action that opens a confirm dialog
("Suspend this member?"). Confirming PATCHes
suspend: true(User.status → SUSPENDED: login + in-flight blocked, memberships kept — the shared TASK-0132 path). The row's status cell flips toSUSPENDED; unsuspend restoresACTIVE. The API is authoritative — a suspended user's next login/refresh gets403 account_suspended.
4. Policies tab (the five enforcement points)
Each enforcement point is a toggle or input, with live validation (bounds
from the API; the file-size input is plan-capped — the effective MB shown
is min(stored, plan)):
| Control | Default | On |
|---|---|---|
| Require 2FA | off | org logins need the TOTP step |
| Enforce SSO | off | non-SSO org logins 403 sso_required |
| Disable guest public shares | off | new public shares 403 (the share page shows the notice) |
| Max file size (MB) | plan cap | uploads over the effective cap 413 (the file picker warns before the pick) |
| Session lifetime (h) | unlimited | refresh at the cap 401 session_expired |
| Allow external embeds | on | off → the preview proxy 403s before any fetch |
A single Save PATCHes the changed fields (audited with old/new values — the change trail IS the policy history). The save button disables once the draft matches the server row.
5. Retention tab
Per-scope policy editor (trash / comments / audit_logs / files): each scope
is a type toggle (PURGE / HOLD) + retainDays input + a Save that
upserts that scope. Defaults: trash PURGE 30, comments PURGE 90,
audit_logs HOLD, files PURGE 0 (no purge).
Run-now — each scope has a card with a Dry-run and an Execute
button. Both POST …/retention/run ({scope, mode}) → 202 processing,
then the tab polls …/retention/runs/:runId for the report:
- Dry-run shows a "Dry-run complete" badge + the would-be counts
("N pages · N blocks · … · X freed") and writes
lastDryRun. - Execute opens a confirm dialog, then purges and shows an "Executed"
badge + the actual counts, writing
lastRun. Execute purges even when the daily cron's execute flag is off (the admin action is deliberate). - A HOLD scope (or files at
retainDays: 0) reportsskippedwith a reason — nothing is purged.
The report is best-effort async (a worker job); if the worker is down the poll times out and the card shows the processing state (see deployment §10.7).
6. Audit tab (the viewer)
A filter bar (action / action-prefix, actor, resource type, workspace,
time window capped at 90 days) + a paginated table. GET …/audit/actions
feeds the action datalist. Each row opens a drawer with the full audit
log row (metadata rendered as JSON).
Export. The export button is content-type-driven:
- ≤ 10k matching rows → the API returns the CSV inline (
200 text/csv); the client reads the raw body and saves it as a local file (a Blob + object URL, since it's a cross-origin response it can't navigate to). -
10k rows →
202 { exportId, cap, total }; the tab shows an async status card (processing → ready) and, once ready, a Download button that fetches the status to get the single-use, 15-minute presigned URL and opens it. The URL is one-shot: a second click (or?redownload=1) gets the status without a URL. One active export per org (409 export_in_progress).
The export is read-only against the audit data (no mutation endpoints
exist); the export itself is audited (audit.export.completed/failed).
7. Share page — the guest-public-share notice
The share page (/w/{ws}/page/{id}/share) reads the member-facing
GET /workspaces/{id}/policy/effective. When
policy.disableGuestPublicShare === true, it shows a destructive-styled
notice ("Your organization has disabled public (guest) sharing") and
disables the "Anyone with the link" radio (labelled "(disabled by your
org)"). The notice is UX only — the enforcement is POST /shares
returning 403 { reason: "guest_public_share_disabled" } for kind: "public"; member/link shares are unaffected. (The unused ShareDialog
component is not this surface — the route page above is.)