Product Concepts
This page documents the current product concepts used across the repo. The names and boundaries here are grounded in @veref/contracts, the Prisma schema, @veref/workflows, and the current app and API surfaces.
Primary actors
Recruiter
The recruiter is the main operator in the system.
- works inside the recruiter desk
- owns candidate progress and review decisions
- approves drafts, reminders, and client-facing summaries
- escalates risk, fraud, or coverage gaps
Coordinator
The current auth model includes coordinator as a lower-ranked recruiter-side role. Coordinators still work on behalf of a tenant but have less authority than recruiter, admin, or owner roles.
Admin and owner
Admin and owner roles exist in the repo’s role model for tenant access checks. They are still tenant-scoped operators, not a separate global back-office persona.
Candidate
The candidate is a public-flow participant.
- grants permission
- provides or confirms referee contacts
- does not need recruiter workspace access
Referee
The referee is also a public-flow participant.
- receives outreach by email or SMS
- submits structured responses
- contributes evidence to the review package
Agent and tech-team actors
Ops feed messages can be sent between agent, tech-team, and recruiter actors. These exist to make handoffs visible inside the product instead of burying them in external chat tools.
Core entities
Tenant
Agency account boundary. Most product state hangs off Tenant.
Recruiter
Tenant member with a role and optional Clerk user mapping.
Candidate
Represents the person being reviewed. Current fields include:
- assigned recruiter
- stage
- permission granted flag
- contact details
The permissionGranted field matters because the current operating model treats candidate permission as a workflow gate.
Reference request
The main workflow container for a candidate’s reference process.
- belongs to a tenant
- points to a candidate
- can optionally point to a recruiter
- owns contacts and communication deliveries
Reference contact
One referee or reference source attached to a request.
Reference response
Structured answers and risk signals attached to a contact.
Communication delivery
Represents outbound channel activity such as email or SMS.
Agent suggestion
Machine-generated recommendation or draft tied to a tenant and optionally a candidate. The schema already models approval explicitly.
Lifecycle states
Candidate-level lifecycle
The candidate record itself carries a free-form stage string. Current workflow snapshots use stages such as:
- sourced
- permission pending
- fraud review
- reference review
- client review
These are product states surfaced to recruiters, not a rigid workflow engine enum.
Reference request lifecycle
The persisted ReferenceRequestStatus enum is:
draftcandidate_pendingcollectingcompletereview
This is the clearest repo-backed lifecycle for the reference-check process.
Recruiter-control versus public-flow boundary
This is the core Veref product concept.
Recruiter-controlled surfaces
- dashboard metrics
- candidate list and spotlight
- reference queue
- signal alerts
- outreach approvals
- ops threads
- activity history
Public-flow actions
- candidate permission capture
- candidate referee release
- referee outreach receipt
- referee response submission
Public participants move the workflow forward, but the system still centers the recruiter as the person who sees the full context, the risk layer, and the final share decision.
Evidence-backed review model
Veref’s summaries are supposed to stay attached to evidence.
- signal alerts include evidence text
- workspace spotlight includes strengths, risks, and a next step
- activity history records who or what advanced the workflow
- ops threads preserve human and agent handoffs
That matters because the product is aimed at high-trust recruiting workflows where unsupported AI copy is not enough.
Current non-goals implied by the repo
- no general-purpose CRM model
- no candidate self-service workspace with the same privileges as recruiters
- no separate product line for global admin workflows
- no complete ATS replacement in the current schema
Read User Flows next for how these concepts play out across the actual product paths.