User Flows

This page describes the end-to-end flows the current repo is built around.

Recruiter workspace flow

1. Open the recruiter desk in apps/app.
2. Start from overview, inbox, activities, candidates, references, signals, outreach, or automation.
3. Review the dashboard metrics and candidate spotlight.
4. Inspect the reference queue to see which candidates are blocked on permission, missing referee coverage, or ready for client packaging.
5. Review alerts and outreach drafts before advancing the workflow.
6. Use ops threads when the next action needs coordination between recruiter, agent, and tech-team actors.
7. Edit candidate profile fields inline; profile edits are written to audit events and shown in candidate/reference activity.

This is the primary operator journey. The browser app is the canonical recruiter workstation in the current repo.

Candidate permission-capture flow

1. Recruiter or agent starts a reference request with launchMode: "candidate_intake".
2. Candidate receives a public-flow prompt rather than access to the recruiter desk.
3. Candidate confirms permission and work-history details.
4. Candidate submits or confirms referee contacts.
5. The extraction worker records the intake evidence, creates or updates referee contacts, queues referee outreach, and moves the workflow out of candidate_pending into collection.

Important boundary: the candidate flow is intentionally narrow. It exists to unblock the reference process, not to mirror internal recruiter views.

Referee outreach and completion flow

1. Contacts are attached through candidate intake or a manual_references launch.
2. Referee contacts include both email and phone so email/SMS outreach and reminders can be scheduled.
3. Communication previews are generated.
4. If providers are configured, email uses Resend and SMS uses Twilio.
5. If providers are not configured, the repo still returns preview behavior so the workflow can be exercised in development.
6. Referees receive the request, respond in the public reference chat, and contribute structured evidence.
7. Completed referee responses cancel remaining reminders for that contact; when every contact has responded, the request moves to recruiter review.

This flow is current-repo aligned because the communication layer already distinguishes configured sends from preview mode.

Review and reporting flow

1. Recruiter sees completion progress in the reference queue.
2. Signal alerts highlight fraud, credibility, or coverage issues.
3. Workspace summaries combine strengths, risks, and recommended next steps.
4. Recruiter approves the final movement of the candidate toward client review.

The current repo does not position the system as fully autonomous. The final review decision still sits with the recruiter.

Ops and message flow

1. Recruiter, agent, or tech-team actor creates a tenant-scoped ops message.
2. The thread appears in the ops feed with priority, tags, participants, and requested action.
3. The feed becomes the coordination layer for operational work that affects the hiring workflow.

Ops messages are persisted in Prisma. Preview ops data is only available when VEREF_ENABLE_PREVIEW_FALLBACK=1 is explicitly enabled for development.

Current repo routes:

• GET /v1/tenants/:tenantId/ops/feed
• POST /v1/tenants/:tenantId/ops/messages

Surface-to-surface flow

Browser app to API

The recruiter workspace depends on tenant-scoped product endpoints and public request creation.

Browser app to desktop

The desktop app is a parallel recruiter surface for local power workflows. It surfaces:

• local agent availability
• runtime and agent skill catalogs
• symlink health for .claude and .codex

Browser extension to recruiter app

The extension captures page and selection context, then hands recruiters back into the main app.

Mobile to recruiter workflow

The mobile app is positioned as a notification and triage companion for recruiter moments that cannot wait for desktop.

What is not a current user flow

• a broad candidate account dashboard
• an end-customer or client portal
• a standalone fraud-ops console
• a persisted requisition-management flow

Those may be future directions, but they are not the current shipped paths and should not be documented as if they already exist.