Role Flow Check (2026-04-26)

Last reviewed: 2026-04-26

This document records a code-based user-flow check for the current OfferReview worktree. It is not a product spec; it reflects what the code appears to do today.

Sources checked

• src/app/dashboard/page.tsx
• src/app/api/dashboard/route.ts
• src/components/AppHeader.tsx
• src/lib/auth/rbac.ts
• src/app/api/candidates/*
• src/app/manager-review/[token]/page.tsx
• src/lib/managerReviewAccess.ts
• src/lib/candidateDeepDive.ts
• src/app/(app)/candidates/[id]/*
• src/app/admin/*
• src/app/api/access-requests/*
• src/app/api/users/*
• src/app/api/settings/*

Shared flow notes

• Real product entry points are /login and /dashboard. src/app/page.tsx is still the default Next.js starter page.
• Global nav currently exposes Dashboard, Candidates, Notifications, and Settings to all signed-in roles.
• Upload is shown only for Admin and HR.
• Admin-style nav currently includes:
  • Access Requests for Admin and SMO
  • Users for Admin, HR, and SMO
  • Org Setup for everyone with the app shell
  • Deep-Dive Questions for SMO only
  • Templates for Admin only

Candidate stage flow

• Current schema status path:
  • NEW
  • HR_SCREENED
  • MANAGER_EVAL_PENDING
  • MANAGER_REVIEWED or CANDIDATE_DEEP_DIVE_PENDING
  • TO_SMO
  • APPROVED / REJECTED / KIV
• Manager assignment and candidate detail access are assignment-based for Manager role.
• SMO candidate detail access is limited to:
  • MANAGER_REVIEWED
  • TO_SMO
  • APPROVED
  • REJECTED
  • KIV

HR flow

• Entry:
  • Dashboard subtitle: HR Screening Queue
  • Primary actions: Upload Resume, View Candidates
• Dashboard queue currently includes:
  • NEW
  • HR_SCREENED
  • CANDIDATE_DEEP_DIVE_PENDING
• Candidate flow:
  • Create candidate via upload-resume flow
  • Complete HR screening from candidate detail
  • Assign hiring manager after HR_SCREENED
  • View candidate overview/documents/audit and, in current worktree, manage deep-dive delivery without seeing the SMO-only answers
• Org/admin-style tools available from current nav or APIs:
  • user list page
  • organization setup

Manager flow

• Entry:
  • Dashboard subtitle: Your Evaluations Pending
• Candidate visibility:
  • candidate list API filters managers to hiringManagerId = currentUser
  • candidate detail access is also assignment-based
• Main path:
  • open assigned candidate
  • fill scorecard / manager review
  • if recommendation is PROCEED, candidate moves to CANDIDATE_DEEP_DIVE_PENDING and a candidate questionnaire invite is attempted
  • otherwise candidate moves to MANAGER_REVIEWED
  • escalate to SMO is blocked when recommendation is PROCEED but no deep-dive response exists yet
• Alternate path:
  • assignment now generates a long-lived manager magic link at /manager-review/[token]
  • link becomes invalid if review is completed, reassigned, expired, or no longer matches the current assignment

SMO flow

• Entry:
  • Dashboard subtitle: Final Decisions Pending
  • dashboard includes CandidateStrengthAnalytics with AI compare enabled
• Candidate visibility:
  • dashboard queue only shows TO_SMO
  • candidate list API currently allows SMO to see MANAGER_REVIEWED, TO_SMO, APPROVED, REJECTED, and KIV
• Candidate detail:
  • tabs include Overview, Radar, Deep Dive, SMO Decision, SMO Interview, Documents, Audit
  • when a deep-dive response exists, SMO defaults into the Deep Dive tab
  • CandidateDeepDiveTab is SMO-only; HR/Admin can manage delivery but cannot view answers there
• Main actions:
  • review deep-dive answers and AI analysis
  • review SMO interview questions / artifacts
  • manage the deep-dive question bank
  • finalize decision through /api/candidates/[id]/decision

Admin flow

• Entry:
  • dashboard shows pending access requests and failed outbox count placeholder
• Main admin actions available in current codebase:
  • review and decide access requests
  • manage users, roles, departments, positions, templates, notification rules, audit, email templates
  • settings API ownership is admin-only
  • impersonation is available for Admin; SMO also has read/impersonation support on the users page
• Organization setup now includes:
  • department CRUD
  • position CRUD
  • active job-description upload/paste flow

Observed mismatches / risks

1. Manager dashboard shows unassigned cases that managers still cannot open

• Dashboard API includes unassigned HR_SCREENED cases in the Manager queue.
• Candidate access logic still blocks managers from opening candidate detail unless already assigned.
• Likely user-visible result: Review & Claim can lead to a forbidden detail page.

2. Settings is in the shared nav, but settings APIs are admin-only

• Settings is shown in the main nav for every signed-in role.
• /api/settings and /api/settings/notification-rules currently require ADMIN.
• Likely user-visible result: non-admin users can reach the page but see a load error / unavailable state.

3. HR can open the users page, but cannot load user detail

• /api/users allows ADMIN, HR, and SMO.
• /api/users/[id] GET allows only ADMIN and SMO.
• Likely user-visible result: HR can see the list but selecting a user fails to load the detail panel.

4. HR dashboard uses a stale ?tab=assign link

• HR dashboard maps HR_SCREENED action to /candidates/:code?tab=assign.
• Candidate detail valid tabs do not include assign.
• Current behavior likely falls back to the HR default tab, so this is low severity but stale.

5. Root app route is not wired into the product flow

• / is still the starter page from create-next-app.
• This does not break signed-in role flows directly, but it is inconsistent with the rest of the app shell.

Recommended doc usage

• Use docs/PROJECT_CONTEXT.md for the short current state.
• Use this file when the task depends on actual role-by-role workflow behavior.
• Re-run this flow check after any changes to dashboard routing, role gating, candidate statuses, manager-review links, or deep-dive delivery.