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.

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

Candidate permission-capture flow

1. Recruiter starts or resumes a reference request.
2. Candidate receives a public-flow prompt rather than access to the recruiter desk.
3. Candidate confirms permission.
4. Candidate submits or confirms referee contacts.
5. The workflow moves out of candidate_pending and 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 to the reference request.
2. Communication previews are generated.
3. If providers are configured, email uses Resend and SMS uses Twilio.
4. If providers are not configured, the repo still returns preview behavior so the workflow can be exercised in development.
5. Referees receive the request, respond, and contribute structured evidence.

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.

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.