Employee Referrals

1. Overview

Employee-driven candidate sourcing with referral-bonus tracking (candidate_referrals). Embedded-masters candidates. Cross-domain handoffs to PAYROLL (bonus payout) and EMP-EXP (engagement signal).

2. Entity summary

Name	Description
Referrals	Employee-submitted candidate suggestion linked to a requisition. Tracks the referring employee, candidate, status, and any payable bonus.
Candidates	Person known to the recruiting org, with or without an active application. Carries contact details, resume, tags, GDPR consent, and source. Distinct from Employee until hired.

flowchart TD
  classDef master fill:#d4f4dd,stroke:#27ae60,color:#0b3d20;
  classDef embedded_master fill:#fff4cc,stroke:#c79100,color:#5b4500;
  classDef platform_builtin fill:#e0e0e0,stroke:#424242,color:#1a1a1a;
  candidate_referrals["Referrals"]
  candidates["Candidates"]
  users["Users"]
  candidate_referrals -->|"introduces"| candidates
  candidate_referrals -->|"has referring employee"| users
  class candidate_referrals master;
  class candidates embedded_master;
  class users platform_builtin;

3. Entities catalog

#	data_object	role	mastered in	necessity	pattern flags	notes
1	`candidate_referrals` (Referrals)	master	-	required	-	-
2	`candidates` (Candidates)	embedded_master	`ats-candidate-crm`	required	personal_content	-

4. Aliases and industry synonyms

(no industry-scoped aliases or non-synonym alias types loaded for this scope; generic synonyms are omitted as common knowledge.)

5. Relationships

5.1 Intra-scope edges

from	verb	to	cardinality	kind	necessity	owner_side	notes
`candidate_referrals`	introduces	`candidates`	one_to_many	reference	required	target	-

5.2 Built-in edges (`users` and other platform built-ins)

from	verb	to	cardinality	necessity	owner_side	notes
`candidate_referrals`	has referring employee	`users`	many_to_many	required	source	-

5.3 Cross-scope edges

from	verb	to	cardinality	necessity	notes
`skill_profiles`	feeds	`candidates`	one_to_many	optional	-
`candidates`	submits	`job_applications`	one_to_many	required	-
`recruitment_sources`	attributes	`candidates`	one_to_many	required	-
`recruitment_agencies`	sources	`candidates`	one_to_many	required	-
`recruitment_events`	attracts	`candidates`	one_to_many	required	-
`talent_pools`	groups	`candidates`	many_to_many	required	-
`candidates`	becomes	`employees`	one_to_one	required	-
`candidates`	becomes pre-employee	`pre_employees`	one_to_one	required	-

6. Cross-domain context

6.1 Master consumers (other modules / domains that embed this scope’s masters)

data_object	other module / domain	role	necessity	notes
`candidate_referrals`	PAYROLL-EARNINGS-DEDUCTIONS (Earnings, Deductions and Garnishments) - PAYROLL	consumer	required	-

6.2 Outbound handoffs (events this scope publishes)

source module	target domain	target module	trigger_event	payload	integration	friction	description
ATS-REFERRALS	PAYROLL	PAYROLL-EARNINGS-DEDUCTIONS	`candidate_referral.bonus_earned`	`candidate_referrals`	api_call	medium	Referral-bonus eligibility milestone reached; PAYROLL pays bonus via off-cycle or next regular run.
ATS-REFERRALS	ATS	ATS-CANDIDATE-CRM	`candidate_referral.submitted`	`candidates`	lifecycle_progression	low	-

6.3 Inbound handoffs (events this scope reacts to)

(no inbound handoffs whose payload is in this scope.)

6.4 Master providers (modules / domains that own masters this scope embeds)

data_object	role here	necessity	canonical owner(s)	slice notes
`candidates`	embedded_master	required	ATS-CANDIDATE-CRM (ATS)	-

7. Lifecycle states (per touched entity)

`candidate_referrals` (Referral)

order	state_name	initial?	terminal?	requires_permission?	derived gate	description
1	`submitted`	✓	-	-	-	Employee submitted a referral candidate against a requisition.
2	`under_review`	-	-	-	-	Recruiter is evaluating the referred candidate.
3	`converted`	-	✓	-	-	Referral became a job application in the ATS pipeline.
4	`bonus_payable`	-	-	✓	`ats-referrals:pay_referral_bonus`	Hire confirmed; gated step to approve the referral bonus payout.
5	`bonus_paid`	-	✓	-	-	Referral bonus has been issued to the referring employee.
6	`rejected`	-	✓	-	-	Referral not pursued.

`candidates` (Candidate)

This scope holds candidates as embedded_master; the canonical state machine is owned by ATS-CANDIDATE-CRM.

order	state_name	initial?	terminal?	requires_permission?	derived gate	description
1	`prospect`	✓	-	-	-	Person known to the recruiting org with no active application.
2	`active`	-	-	-	-	Candidate has at least one open application or is actively engaged.
3	`hired`	-	✓	✓	`ats-candidate-crm:hire_candidate`	Candidate accepted an offer and converted to employee.
4	`do_not_hire`	-	✓	✓	`ats-candidate-crm:flag_do_not_hire`	Candidate flagged as ineligible for future consideration; gated decision.
5	`archived`	-	✓	-	-	Candidate kept in the database but not active in any pipeline.

8. Permissions and business rules (derived)

8.1 Permissions

permission	tier	description	included in `:admin`?
`ats-referrals:read`	baseline-read	Read access to every entity in the module	✓
`ats-referrals:manage`	baseline-manage	Edit operational records	✓
`ats-referrals:admin`	baseline-admin	Edit reference data and inherit every workflow gate below	-
`ats-referrals:pay_referral_bonus`	workflow-gate (lifecycle)	Transition `candidate_referrals` into state `bonus_payable`	✓

8.2 Business rules

(no flag-derived business rules.)