Skip to main content

VIEWS_BY_ROLE.md — human.work

Per-screen design specification for every role. Cross-reference: INFORMATION_ARCHITECTURE.md, USER_STORIES.md, IMPLEMENTATION_STATUS.md, GLOSSARY.md. Last updated: 2026-05-04.

Each screen follows the template:

### Screen: <route>
- Layout
- Sidebar / left rail / top nav (where applicable)
- Main area
- Key interactions
- User stories fulfilled
- Known gaps

1. Client (/client/*)

Route migration (complete): Client admin settings moved from /portal/admin/* (and its sibling /client/admin/*) to /client/settings/*. The /portal/* prefix is gone from the codebase; old in-app /client/admin/* paths redirect. New client work uses the /client/* prefix.

Client Roles​

All client users have an orgRole in OrgMembership. This gates access within /client/settings/*.

RoleWhoTeam viewTeam manageChannelsBillingTransfer ownership
Owner1 per client, invited by AM✅✅✅✅✅
AdminSet by owner/admin✅✅✅✅❌
BillingSet by admin✅❌❌✅❌
MemberDefault✅ (read-only)❌❌❌❌
  • Team list is visible to all roles — team management (invite/remove/role change) is Admin and Owner only.
  • See GLOSSARY.md → Client Roles for full role definitions.

The client interacts with one consistent identity — the Specialist (e.g. "Bob"). Internal team composition (Humanity Protocol Experts + AI Agents) is invisible. Every view enforces this principle.

The client portal is intentionally minimal. Its job is: (1) let a client team chat with their Specialist, and (2) let the client admin manage their own team, channels, and billing. Service configuration (agent name, confidence threshold, slug, whitelist) is handled by the AM during onboarding — not by the client. There is no helpdesk, no ticket queue, no analytics dashboard, no support inbox for the client's own end-customers (Acme Financial does not have customers using human.work — Amy IS the end user).

Screen: /client/chat (and /client/chat/[id])​

Layout — Full-screen split: 256px sidebar on the left, flex chat panel on the right.

Sidebar (Sidebar inside PortalChat.tsx)

  • Workspace header (top, 44px) — Slug-letter avatar (claret square, 22px) + slug subdomain text (acme.h.work). Border-bottom 1px subtle.
  • Your Specialists group — Section label "YOUR SPECIALISTS" (uppercase, 10px, muted). Each specialist row: 28px circular avatar (claret), name in 12px/600, role label ("Primary specialist" / "Specialist") in 11px/muted. Active row: 3px accent left border + accent-subtle bg. Hover: bg-hover. Click → expert profile preview pane in main area.
  • Your Threads group — Section label "YOUR THREADS" with + New Thread button on the right (claret text, 11px/600). Each thread row: 36px Specialist avatar with green online dot if status is active/open, thread label (12px/500), last-message snippet (11px/muted), relative time, unread count pill (claret). Inline rename pencil icon on hover. Active row: 3px accent left border + accent-subtle bg.
  • UserFooter (bottom) — avatar (claret, 32px), name + email, theme toggle (sun/moon, 16px), role-aware footer links ("Account Settings", "Billing"), "Sign out" button.

Main panel (ChatPanel inside PortalChat.tsx)

  • Header (53px) — hamburger to toggle sidebar (mobile), Specialist avatar + green online dot, Specialist name + status line ("Online · Support Specialist"), ChannelBadge (right). Status pill is read-only for clients ("Active" / "Resolved").
  • Empty state (no thread selected) — WorkforceEmptyState: section label "YOUR WORKFORCE", h2 "Ready to help", subtitle "Delegate work to your AI team — just like messaging a teammate." Below: a single Specialist card (avatar, name, "Support Specialist · h.work", "Online now" badge, claret "Message" button). When multiple specialists are configured, a stack of cards.
  • Message stream — Padded vertically (14px) and horizontally (16px), gap 10px between bubbles.
    • Outgoing (user): claret background, 14px white text, 18px corner radius with 4px tail in the bottom-right corner (border-radius 18px 18px 4px 18px), aligned right, max 76% width.
    • Incoming (Specialist): bg-surface, 1px subtle border, 14px primary text, 18px radius with 4px tail in the top-left (4px 18px 18px 18px), aligned left, max 76% width. Avatar (26px claret) + small "AI" / "Human review" badge inline above the bubble (see C-W5).
  • Composer (bottom) — Slack-style: attach button (paperclip, 17px, muted), auto-grow textarea (1–5 rows, max 120px, 20px pill radius, bg-canvas), send button (34px circle, claret when text present, bg-hover when empty).

Key interactions

  • Click + New Thread → POST /conversations → empty thread opens with composer focused.
  • Type and press Enter → optimistic message appended, then real message replaces optimistic. Shift+Enter for newline.
  • Click thread row → opens thread, marks all unread as read (clearThreadUnread), updates URL to /client/chat/[id], persists "last viewed thread" per user.
  • Hover thread row → ✏️ rename button appears. Click → inline input, Enter to commit (stored in localStorage hw_threadNames).
  • Hover sidebar specialist → click → expert profile preview pane (read-only) with claret "Message" button to start a thread with them.
  • Toggle theme via UserFooter → flips [data-theme], persists in localStorage.

User stories fulfilled — C-W1, C-W2 (partial), C-W4, C-W5 (AI/Human-review badge), C-W6 (search not surfaced in sidebar yet — see Gaps), C-CH1.

Known gaps

  • C-W8 — high-stakes approval banner not surfaced in client view; only appears for experts (pendingApprovalMsg && isExpert). Needs a client-facing "Awaiting your approval" banner with Approve / Reject controls.
  • C-W6 — search exists in API (GET /conversations/search), but no search input in the sidebar. Add a top-of-list search affordance.
  • C-W7 — agentic task progress: backend tracks but no inline progress timeline in the chat thread.
  • Real-time: Socket.io is wired and polling is the fallback; WebSocket-driven push has not been verified end-to-end.

Retired: /client/tickets/*​

The Tickets nav item was retired from the client portal. Conversations with the Specialist live in /client/chat as threads — there is no parallel "ticket inbox" surface for clients. (The legacy /client/admin/tickets route redirects to /client/chat. Ticket page files still exist under /client/tickets/* but are no longer linked from any nav.)

A trackable structured work-item concept may return for clients in the future to support multi-step agentic tasks (USER_STORIES.md C-W3, C-W7) but the design has not been redrawn.

Redirected: /client/settings → /client/settings/profile​

The bare /client/settings route redirects to /client/settings/profile. See Screen: /client/settings/profile below.

Retired: /client/admin/tickets​

Removed in the 2026-05-02 client portal refactor. Clients converse with the Specialist via threads in /client/chat; they do not triage a ticket queue — that's the operator (Expert) view at /workspace/queue. The legacy route now redirects to /client/chat.

Redirected: /client/admin/team → /client/settings/team​

This route redirects to /client/settings/team. See Screen: /client/settings/team below.

Screen: /client/settings/profile​

Layout — Settings shell (/client/settings/layout.tsx) with left sidebar nav + centered single-column form, max 720px.

Sidebar nav — Profile (always), Team (always), Channels (Admin/Owner only), Billing (Admin/Owner/Billing only).

Main content

  • Display name, avatar upload, phone, title, bio.
  • Preferences: theme toggle, time zone.
  • Notifications: email digest frequency, browser push (future).

Roles — All roles.

User stories fulfilled — C-O1 (profile completion follow-up).

Screen: /client/settings/team​

Layout — Settings shell + main content area.

Main content (all roles — view)

  • Page header "Team".
  • Members table: avatar, name, email, role badge (Owner → gold, Admin → blue, Billing → purple, Member → gray), status (active / pending), joined date.
  • Self row highlighted with "(you)" label.

Admin/Owner only additions

  • "+ Invite Member" claret button → modal (email + role select).
  • Role <select> per row (inline edit; cannot exceed own role; cannot demote last admin/owner).
  • "Remove" button per row (confirm modal; cannot remove owner row).
  • Pending invites section with Resend / Revoke actions.

Owner-only section (bottom)

  • Transfer Ownership — select new owner from current members (Admin or above); confirm modal (destructive-level).

Non-owner section (bottom)

  • Leave team — stub UI; API pending issue #148.

Key API calls

  • GET /admin/members — list members
  • POST /admin/members/invite — invite
  • PATCH /admin/members/:id/role — role change
  • DELETE /orgs/:orgId/members/:userId — remove
  • POST /orgs/:orgId/transfer-ownership — transfer (owner only)

User stories fulfilled — C-T1 (✅ invite), C-T2 (✅ remove), C-T5 (✅ transfer ownership), C-T6 (⚠️ leave team — partial).

Known gaps — C-T6 leave workspace API (issue #148).

Redirected: /client/admin/billing → /client/settings/billing​

This route redirects to /client/settings/billing. See Screen: /client/settings/billing below.

Screen: /client/settings/billing​

Layout — Settings shell + main content.

Roles — Admin, Owner, Billing.

Main content (top to bottom)

  • Current plan card — plan name (Starter / Pro / Enterprise), price, "Upgrade" button (if not Enterprise).
  • Usage — quota gauge (messages used / quota), period reset date. Color: teal → warning at 75% → danger at 90%.
  • Payment method — last 4, expiry, "Update" button → Stripe Customer Portal.
  • Trial banner if in trial — days remaining + "Add payment method to keep service" CTA.

Key interactions

  • Click Upgrade → Stripe checkout in a new tab.
  • Click Update → Stripe Customer Portal in a new tab.

User stories fulfilled — C-B1, C-B2.

Known gaps

  • C-B3 — invoice history / download. Add a simple table below "Payment method" listing invoice number, date, amount, "Download PDF" link.

Redirected: /client/admin/channels → /client/settings/channels​

This route redirects to /client/settings/channels. See Screen: /client/settings/channels below.

Screen: /client/settings/channels (and detail / new)​

Roles — Admin, Owner only.

Formerly /client/admin/channels (renamed from /client/admin/integrations in the 2026-05-02 refactor). Legacy routes redirect here.

Layout — Admin sidebar + main content. Card grid of available channels.

Main content

  • Page title "Connected Channels".
  • Section "Connected": channel cards with status badge (green = healthy, amber = warn, red = error), "Manage" link.
  • Section "Available": uncolored cards for not-yet-connected channels with "Connect" button.
  • Cards: Email (always-on default), Slack, WhatsApp, Telegram, Microsoft Teams (greyed — "coming soon"), WeChat (greyed).

Detail view ([id])

  • Channel name + health badge.
  • Configuration: webhook URL (with copy button), inbound whitelist, test inbound button.
  • Last 10 inbound events (timestamps, status).
  • "Disconnect" button (destructive — confirm modal).

New view

  • Picker grid → OAuth flow per channel (Slack OAuth, Telegram bot token, etc.).

User stories fulfilled — C-O2 (Slack), C-O3 (Email), C-C1 (channel health), C-C2 (WhatsApp).

Known gaps — C-C3 (outbound webhooks), C-C4 (Teams).

Retired: /client/admin/analytics​

Removed in the 2026-05-02 refactor. Clients do not currently get an analytics dashboard — the previous page was placeholder and risked exposing operator-side mechanics (AI-handled %, expert review rate). When a client-facing analytics surface is reintroduced (USER_STORIES.md C-V*), it will be a usage dashboard (volume vs. quota, response latency) rather than an operator dashboard. The legacy route now redirects to /client/settings/billing.

Retired: /client/admin/settings​

Removed in the 2026-05-02 refactor. The page exposed configuration that clients should not control — agent name, confidence threshold, slug, whitelist. These are operator-only and are configured by the AM during onboarding (Phase 1.2 / 2.4) and editable post-onboarding by the AM/superadmin in /ops/clients/[id]. The legacy route now redirects to /client/settings/team.

If a client needs to change the threshold or whitelist, they contact their AM.

See OPEN_DECISIONS.md OD-1 for the open question on whether a read-only surface ("Your account is currently set to 'Always Reviewed by Expert'") should be reintroduced for client transparency.

2. Expert (/workspace/*)

The Expert workspace is Humanity Protocol's internal operations surface — used by HP employees (e.g. David Kim, Charlie Osei) who review AI drafts and respond as the Specialist persona to a client team. It is not visible to clients and is not a feature of the client-facing product. The architecture (queue / inbox / collab rooms / agentic-task plan review) is closer to Intercom-for-our-own-team than to anything a client sees.

The Expert's home is the queue. Every other route is reachable via the top nav but the queue is where work happens.

Screen: /workspace/queue and /workspace/queue/[id]​

Layout — Split-pane:

  • Left rail (300px) — queue list with filters + SLA strip on top.
  • Right pane (flex) — currently selected ticket. The right pane is itself a 40/60 split: Client View (left, ~40%) over the customer thread, Expert Workspace (right, ~60%) for the AI draft + actions. The pane header reads "Client Conversation with {customer}".

On mobile (≤768px) the layout collapses to tabs (Queue / Detail) — queue-mobile-tabs class in globals.css.

Left rail (queue list)

  • Header — new-item count pill ("N new", claret) + pending count pill (right, danger). No standalone title row.
  • Client tabs — horizontal scrollable tabs (All Clients · Acme · …) when the expert serves multiple clients.
  • Status tabs — Pending · In Review · Resolved (40px tall, claret bottom-border on active).
  • SLA metrics strip — three metrics inline: Avg resolve, SLA met %, Resolved count. SLA % is colored success/warning/danger by threshold.
  • Risk filter pills — All · Critical · High · Medium. Sorting is always newest-first; there is no sort toggle.
  • Assignee filter pills — All · Mine · Unassigned.
  • Ticket rows (64px min height) — left risk bar (3px), customer name + relative time, 2-line message preview, badge row (risk badge with theme-aware bg/text token, confidence %, AssigneePill ("You" / "Assigned" / "Unassigned"), ChannelBadge).
  • Selected row: accent-subtle bg + accent left bar overrides risk bar. Hover: bg-hover.

Right pane (TicketDetail)

  • Header — #ticketId, risk badge, channel badge, customer name, status dropdown (open / pending / resolved / snoozed / archived), "Assign to me" button.
  • Customer thread — full message history with the customer (CustomerThread component or inline rendering).
  • AI suggestion panel — collapsible card: AI draft text (editable textarea), ConfidenceBar (0–100, color-coded), tools used (chips), data retrieved (collapsible), "Accept & Send", "Edit", "Ignore & Write" buttons.
  • Send-as-Specialist composer — textarea + "Send as [Specialist]" claret primary button.
  • Action bar — Resolve, Defer 24h (with custom-time picker), Reassign (pool dropdown), "+ Internal note" (toggles dashed amber composer for internal-only messages).
  • Internal collab thread — inline below the customer thread, dashed amber border, only visible to experts.

Key interactions

  • Click Accept & Send → respond() API → message sent as Specialist → row marked resolved → next ticket auto-selected.
  • Edit AI draft → live textarea → click "Send as [Specialist]" → same flow.
  • Defer 24h → defer() → row removed from Pending, returns when deferred_until elapses.
  • Reassign → opens pool picker → reassign() → row removed.
  • Add internal note → toggles composer to dashed-amber mode → POSTs with is_internal=true.
  • Status change → PATCH /conversations/:id/status.
  • Auto-refresh queue every 10s; new items animate in with the "N new" pill incrementing.

User stories fulfilled — E-R1 through E-R14, E-A1 through E-A4 (handoff to /workspace/tasks), E-L1, E-C1/C2 (Collab tab cross-link).

Known gaps

  • E-R10 — defer UI not yet confirmed in the frontend (backend complete).
  • E-R11 — reassign UI not yet confirmed in the frontend (backend complete).
  • E-L2 — correction error-type tagging not in the resolve flow.
  • E-P3 — no push notifications when a critical item arrives.
  • E-C3 — no inline ticket-attached discussion thread; experts collaborate in /workspace/collab rooms but cannot anchor a discussion to a specific ticket.

Screen: /workspace/collab​

Layout — Split-pane: left rail rooms list (220px), right pane room thread.

Rooms list

  • Each room row: room name (e.g. "general", "kyc-pool"), unread count pill, last-message snippet, relative time.

Right pane

  • Header: room name, member count, settings icon.
  • Message stream: same bubble pattern as chat but without the AI/Human-review badge (experts only).
  • Composer: same Slack-style as chat with attach + send.

User stories fulfilled — E-C1, E-C2.

Known gaps — E-C3 (no per-ticket inline discussion).

Screen: /workspace/tasks (Agentic task plan review)​

Layout — Split-pane: left task list, right task detail.

Task list

  • Filter pills: All · Pending Approval · Running · Failed · Done.
  • Row: task name, originating ticket link, status badge, # steps, # pending approvals, created time.

Task detail

  • Header: task name, originating customer thread link.
  • Step list (vertical timeline) — each step has: number, name, parameters (JSON / form preview), tool name, AI-confidence bar, status (queued / pending approval / approved / rejected / running / done / failed).
  • Step actions (when pending approval) — "Approve" (claret), "Reject" (with required textarea for feedback).
  • Bottom: "Approve all remaining" button (with confirm modal — destructive in spirit since it auto-approves).

User stories fulfilled — E-A1 through E-A4.

Known gaps

  • Tool execution itself is a stub (issue #29). UI ready, runtime not.

Screen: /workspace/analytics​

Layout — Single-column dashboard with date-range picker top-right.

Sections

  • Stat cards: queue depth, avg resolve time, tickets handled (today / week / month), my SLA %.
  • Volume chart (per day, stacked by AI vs Expert).
  • Confidence histogram (AI confidence distribution for items I reviewed).
  • Top request types (bar chart).
  • Pool comparison: my metrics vs pool average.

User stories fulfilled — E-P1 (pool depth), E-P2 (personal performance).

Known gaps — none for spec.

Screen: /workspace/pools​

Layout — Card grid, one card per pool.

Card — pool name, domain, member count, current queue depth, SLA % (last 7 days), "View" → pool detail (gap: no detail page yet).

User stories fulfilled — E-P1, E-O3.

Known gaps — E-O3 (assigned pools view); pool detail page not built.

Screen: /workspace/settings​

Layout — Single-column form.

Sections

  • Profile (name, email, avatar).
  • Skills / domains (tag input — pulls from User.skills array).
  • Pools I'm a member of (read-only list, link to /workspace/pools).
  • Notification preferences (in-app, email, push when implemented).
  • Availability (on-call toggle, future).

User stories fulfilled — E-O2 (profile + tagging), E-O3 (assigned pools).

Known gaps — E-O2 UI not yet built (backend supports skills array).

3. Account Manager (/ops/*)

Internal Humanity Protocol surface. AMs are HP staff. They onboard new clients (5-step wizard), assign Specialists from the platform pool, manage trial dates and members, and act as the named relationship owner for each assigned org. Not visible to clients.

Shared /ops/* surface. As of 2026-05-03, AMs and Superadmins share the same /ops/* routes. Superadmin is a strict superset — same routes and shell, with additional nav tabs (Queue, Pools, Analytics, Health, Billing, Team) and visibility across all orgs. AM-specific notes in this section apply equally to the SA experience for the same screens; SA-only screens are documented in Section 4.

Screen: /ops/clients (Clients list)​

Layout — Ops top-nav (48px header: logo + role label + tab bar + user avatar at top-right) + main content. Same shell as the Experts workspace. AM tab bar: Clients · Inbox · Settings. SA tab bar: Clients · Inbox · Queue · Pools · Analytics · Health · Billing · Team · Settings.

Main content

  • Header: "Clients" + "+ New Client" claret button.
  • Filter strip: status (All / Trial / Active / Suspended / Archived), search by name or slug.
  • Table:
    • Org name + slug
    • Status pill (active / trial / pending_am_setup / archived)
    • Trial end date (with days-remaining badge if in trial)
    • Last activity (relative time)
    • Specialist (avatar + name)
    • Plan
    • Actions menu (… → Open, Edit, Archive)

Key interactions

  • Click row → /ops/clients/[id].
  • Click "+ New Client" → /ops/clients/new (wizard step 1).

User stories fulfilled — SA-C2 (AM-scoped variant), SA-C3 entry point.

Screen: /ops/clients/new and /ops/clients/[id]/setup/* (5-step wizard)​

Layout — Onboarding-style header (logo + breadcrumbs as a step indicator), centered card max-width 720px, single-column form, "Next" claret button bottom-right + "Back" link bottom-left.

The wizard has 4 user-facing steps (per ops/clients/[id]/setup/* and ops/clients/new):

Step 1 — Company Info (/ops/clients/new)​

  • Fields
    • Company name (required, min 2)
    • Slug (SlugAvailabilityInput — real-time availability check, lowercase + hyphens, immutable post-confirm warning)
    • Workspace URL preview: ``{slug}.h.work (live preview to the right of the slug field)
    • Industry (dropdown)
    • Company domains (multi-input with chip UI; blocks personal-email domains via BLOCKED_DOMAINS)
    • Primary contact: admin email (validates against company domains), admin first/last name, optional phone
    • Country (dropdown), Timezone (dropdown)
    • Website (optional)
  • Validation
    • Slug: unique, format-correct, not reserved.
    • Admin email: must match one of the company domains (otherwise warn + block).
  • CTA — "Continue" → POST createAmOrg → on success, redirect to step2.

Step 2 — Assign Specialist(s) (/ops/clients/[id]/setup/step2)​

  • Search box auto-focused with placeholder "Search specialists…".
  • Specialist pool grid — each card: avatar, name, email (bob@h.work), domain tags, current org count, "Primary?" toggle, "Threshold" slider (0–101).
  • Multi-select; first selected is auto-marked Primary.
  • "Selected (N)" stack at top showing chosen specialists with X to remove.
  • CTA — "Continue" (disabled until ≥1 specialist selected).

Step 3 — AM Profile (/ops/clients/[id]/setup/step-3)​

  • Global AM profile (one-time, shared across all AM's orgs):
    • Display name, avatar upload, email signature line, contact email, phone.
  • Note: "This profile is shown to all your clients. It's saved once and reused across every workspace you manage."
  • CTA — "Continue".

Step 4 — Send Invite (/ops/clients/[id]/setup/step-4)​

  • Phase 0 checklist (Phase0Status from API) — five items, each with ✓ or ⚠️:
    1. Company info confirmed
    2. Slug reserved
    3. ≥1 Specialist assigned
    4. AM profile complete
    5. Trial end date set
  • Below the checklist: "Trial end date" field (default +30 days), editable.
  • "Invite preview" card — exact email body that will go to the client admin, with substituted variables.
  • CTA
    • "Send invite" — claret primary, disabled until all Phase-0 checks pass.
    • Shows current invite status if already sent (sent / accepted / expired). "Resend" / "Revoke" actions.

Key interactions

  • Each step persists progress server-side.
  • "Back" returns without unsaved-changes prompt unless edits in flight.

User stories fulfilled — SA-C1 (AM-scoped), C-O1 (invite-side trigger), supports Phase-0 gate model from PRD.

Known gaps

  • Step 4 trial date field is editable but no UI to extend trial post-invite (covered in Org Detail).
  • No bulk-import wizard for migrating existing clients.

Screen: /ops/clients/[id] (Client detail)​

Layout — Ops top-nav + main content with tabs.

Tabs (AM and SA)

  • Overview — company info card (industry, timezone, invite/billing email, corporate domains, trial end, created), plus a "Continue setup" CTA when status is mid-onboarding.
  • Conversations — list of conversations for this org with status pill and relative-time, click → /ops/inbox?convId=….
  • Specialists — currently-assigned Specialist personas + reassign link to wizard step 2.
  • Team — client member table with name/email, org role pill, joined date.

Tabs (SA-only additions)

  • Tools — live per-org tool-permissions toggles, backed by GET/PUT /orgs/:orgId/tool-permissions.
  • Audit — placeholder card ("Audit log coming soon"). No GET /orgs/:id/audit endpoint yet.

SA action bar (above the tab bar, SA-only)

  • Impersonate — disabled stub ("Coming soon").
  • Reset password — disabled stub ("Coming soon").
  • Change plan — disabled stub ("Coming soon", Stripe management TBD).

SA additions inside the Team tab

  • Inline org-role <select> per member row (owner / admin / member / billing), wired to PATCH /admin/members/:id/role.
  • "Deactivate" stub button per row ("Coming soon").

Key interactions

  • "Edit client" link in the top bar → /ops/clients/[id]/edit.
  • "Continue setup" CTA on Overview when status is pending_am_setup or pending_client_confirmation.
  • "Reassign Specialists" link from Specialists tab.

User stories fulfilled — SA-C3, SA-C4 (assign experts via specialist team), SA-P5 (tool permissions — done).

Known gaps

  • SA-C9 — named lead UI is the gap; today's primary AM is implicit (whoever owns the org).
  • SA-C6/C7/C9 — Impersonate, Reset password, Change plan are scaffolded as disabled stubs (no API).
  • SA-C10 — Audit tab is a placeholder until GET /orgs/:id/audit is added.

Screen: /ops/settings​

Layout — Single-column form.

Sections

  • Personal profile (name, avatar, signature) — for AM, same data as wizard Step 3 (one source).
  • Notification preferences.
  • Theme.

Roles — AM, Superadmin (same shape for both).

User stories fulfilled — supports SA-C9 (foundation for named-lead).

4. Superadmin (/ops/*)

Internal Humanity Protocol operations surface. Cross-org access for the HP operations team — full org list, global queue, pool admin, platform analytics, service health, all-org billing, internal team management. Highest-privilege internal role. Not visible to clients.

Shared /ops/* surface. Superadmin uses the same /ops/* routes as the AM (see Section 3). SA is a strict superset — same shell, same Clients/Inbox/Settings screens, plus additional SA-only nav tabs documented below. SA also sees all orgs (vs. only assigned orgs for AM).

Screen: /ops/clients (SA view)​

Same screen as the AM /ops/clients view (see Section 3) with SA-only additions:

Extra columns — primary AM, MRR, last incident. Row actions — Open, Impersonate (audit-logged), Suspend, Archive.

User stories — SA-C2, SA-C3 entry.

Screen: /ops/clients/new and /ops/clients/[id] (SA view)​

Same wizard and detail as the AM views (Section 3). The detail page adds, for SA only:

  • Tools tab — live per-org tool-permissions toggles via /orgs/:orgId/tool-permissions (SA-P5 — done).
  • Audit tab — placeholder card; full filterable audit log requires GET /orgs/:id/audit (SA-P3 — backend gap).
  • SA action bar — Impersonate / Reset password / Change plan, all rendered as disabled stubs ("Coming soon") since no API exists yet (SA-C6, SA-C7, SA-C9 — backend gap).
  • Team tab — inline org-role <select> per member, plus a disabled "Deactivate" stub.

Screen: /ops/queue (Global queue) — SA only​

Same TicketDetail-style split-pane as /workspace/queue, but with org column visible by default in the list and the org filter prominent. Used for spotting cross-org surges.

User stories — SA-Q1, SA-Q2.

Screen: /ops/pools — SA only​

Layout — Card grid + "+ New pool" claret button.

Pool card — name, domain, member count, current queue depth, members preview (avatar stack), "Manage" link. Pool detail — member table with add/remove, reassign tickets between pools.

User stories — SA-E1, SA-E2, SA-E3.

Known gaps — SA-E4 (leverage ratio analytics).

Screen: /ops/analytics — SA only​

Layout — Single-column dashboard with date-range.

Stat cards — total tickets, auto-resolve %, active experts, MRR. Charts — volume over time, top request types, pool resolution times, AI vs Expert split. All metrics now driven by live data (SA-B4 closed).

User stories — SA-B3, SA-B4.

Known gaps — SA-B5 (per-org cost), SA-E4 (leverage).

Screen: /ops/health — SA only​

Layout — Service grid, one card per service (API, DB, Redis, each channel adapter).

Card — service name, status (green/amber/red), latency, last-error timestamp, link to logs / Grafana. Sticky banner at top if any service is in degraded or outage state.

User stories — SA-P1, SA-P2 (Prometheus metrics surfaced via deep-link).

Known gaps — SA-P4 (per-org channel adapter health).

Screen: /ops/billing — SA only​

Layout — Table view of all org subscriptions.

Columns — org, plan, MRR, status, trial dates, last invoice, next invoice, "Manage in Stripe" link. Row actions — change plan, cancel sub, sync from Stripe.

User stories — SA-B1, SA-B2.

Known gaps — invoice download per org (companion to C-B3).

Screen: /ops/team — SA only​

Layout — Internal users table (AMs, experts, AI operators, other superadmins).

Columns — name, email, platform role, status (active / disabled), last sign-in, pools. Row actions — change platform role, deactivate, reset password.

User stories — SA-C6, SA-C7, SA-E2 (add expert to pool from here).

Screen: /ops/settings (SA view)​

Same shape as the AM /ops/settings (Section 3). Personal profile + theme.

5. Cross-role notes

  • The expert can also visit /client/chat. When they do, all expert-gated controls (status dropdown, assign button, internal note toggle, confidence scores, "Expert" sender label) appear. This is a support-tool affordance documented in frontend/FRONTEND_ARCHITECTURE.md (EXPERT_ROLES section).
  • AM and Superadmin share /ops/*. Superadmin sees all orgs; AM sees only assigned orgs (RLS-enforced). SA-only sub-routes (/ops/queue, /ops/pools, /ops/analytics, /ops/health, /ops/billing, /ops/team) gate on superadmin; AM hitting one is redirected to /ops/clients.
  • The client never sees /workspace/* or /ops/*. Layout guards redirect.
  • Legacy /am/* and /superadmin/* URLs redirect to the matching /ops/* route. Migration is complete — all internal routes use /ops/*.

Owner: Design + Platform team

Last updated on by Ethan