Recruitment Overview

The recruitment system manages the full lifecycle of hiring -- from sourcing talent through to candidate placement. Four core entities drive the workflow: Talent, Job, Candidate, and Pipeline.

Core Entities

Entity	Purpose	Key Identifier
Talent	A user profile stored in a company's talent pool	@@unique([userId, talentPoolId])
Job	A position posted by a company with skill requirements	JobStatus: NEW, IN_PROGRESS, CLOSED, DRAFT
Candidate	A talent applied or assigned to a specific job	CandidateStatus: NEW through APPROVED/REJECTED
Pipeline	A Kanban-style workflow board linking jobs and tracking candidates	Owned by company + user

Recruitment Flow

                        +-----------------+
                        |  Talent Sources |
                        +--------+--------+
                                 |
              +------------------+------------------+
              |                  |                  |
        Manual Entry       CV Upload         Inbound Email
              |                  |                  |
              v                  v                  v
        +---------------------------------------------+
        |              TALENT POOL                     |
        |  (company-scoped, shareable, skill-tagged)   |
        +---------------------+-----------------------+
                              |
                    Match / Apply / Add
                              |
                              v
        +---------------------------------------------+
        |              CANDIDATE                       |
        |  Talent + Job link with status tracking      |
        +---------------------+-----------------------+
                              |
                              v
        +---------------------------------------------+
        |              PIPELINE                        |
        |  Kanban board with stage management          |
        |                                              |
        |  NEW --> IN_REVIEW --> INTERVIEW             |
        |              |            |                  |
        |          WITHDRAWN    APPROVED / REJECTED    |
        +---------------------------------------------+
                              |
                     (if INTERVIEW stage)
                              |
                              v
        +---------------------------------------------+
        |         INTERVIEW SCHEDULING                 |
        |  Slot offers, Jitsi rooms, reminders         |
        +---------------------------------------------+

How Entities Connect

Talent to Candidate: When a talent is matched or applied to a job, a Candidate record is created linking the talent to that job. A single talent can be a candidate for multiple jobs.

Job to Pipeline: Jobs are added to pipelines via PipelineItem records. A pipeline can contain multiple jobs, and each job tracks its own set of candidates through the pipeline stages.

Candidate Status Flow: Candidates progress through defined stages. The status determines where they appear on the pipeline Kanban board:

NEW --> IN_REVIEW --> INTERVIEW --> APPROVED
                         |              |
                     WITHDRAWN      REJECTED

Key Operations Summary

Operation	GraphQL Entry Point	Description
Add talent to pool	addTalent mutation	Creates talent record in company pool
Apply to job	applyAsCandidate mutation	Self-application with auto-provisioning
Add talent as candidate	addTalentAsCandidate mutation	Recruiter assigns talent to job
Update candidate status	updateCandidate mutation	Move through pipeline stages
Schedule interview	createInterviewSlotOffer / confirmInterviewManually	Book via slot offer or direct scheduling
AI matching	candidateJobMatching subscription	Real-time match scoring via background tasks

Multi-Company Context

All recruitment operations are scoped to the user's selectedCompanyId. A user can belong to multiple companies via UserCompanyRole, and the active company context determines which talent pools, jobs, and pipelines are visible.

info

Talent sharing enables cross-company collaboration. Talents can be shared between companies with permission levels (READ_ONLY, EDIT, ADMIN), and talent pools support user, company, and external token-based sharing.

Talent Notes

Recruiters can add internal notes directly to talent profiles, independent of any job candidacy. Unlike candidate notes (which require a talent-to-job link), TalentNotes attach to the talent profile itself. This supports early-stage sourcing workflows where notes need to be captured before any job application exists.

See Talent Notes for details on the API, access control, and frontend integration.

Related Pages

• Talent Management -- talent pools, CV management, sharing
• Talent Notes -- internal notes on talent profiles, independent of job candidacy
• Pipeline System -- stages, status transitions, pipeline sharing
• Interview Scheduling -- slot offers, booking flow, reminders
• Candidate Management -- candidate status pipeline, candidate notes
• Job Management -- job lifecycle, skill requirements, company roles
• Talent Activity -- audit trail of talent lifecycle events
• Talent Pools -- pool management, recommendations, sharing
• CV Collections -- curated CV groups with sharing
• Shared Talent Lists -- cross-functional talent list collaboration
• Inbound Email Processing -- automated job and CV ingestion via email