Referral Code Service
Component Detail
Description
Generates, stores, and retrieves unique referral codes tied to individual peer mentor identities. Ensures codes are stable (one per mentor per organisation), URL-safe, and traceable back to the originating mentor.
referral-code-service
Summaries
The Referral Code Service is the foundational infrastructure that makes peer-to-peer recruitment trackable and attributable. Without stable, unique referral codes tied to each mentor, the organisation cannot measure which mentors are driving growth, cannot reward recruitment behaviour with badges or recognition, and cannot report accurate recruitment figures to funders or leadership. By ensuring codes are URL-safe, persistent, and traceable, this service protects the integrity of the entire recruitment programme's data — preventing scenarios where new members are registered but cannot be attributed to the mentor who recruited them, which would undermine trust in the programme's incentive structure.
This backend service is a core dependency for multiple downstream components: the onboarding screen, the attribution service, and the coordinator dashboard all rely on codes being generated and retrievable. It should be delivered early in the project timeline to unblock parallel development of those dependent components, which can use stub codes during development but require the real service for integration testing. Complexity is medium — the code generation logic itself is straightforward, but the Supabase persistence layer must enforce uniqueness constraints correctly and handle the edge case of mentor deactivation (invalidation or rotation). Database migrations for the referral_codes table must be included in the delivery checklist.
The service wraps a `referral-code-repository` to abstract all Supabase interactions. `getOrCreateReferralCode(mentorId, orgId)` should be idempotent — if a code already exists for the mentor+org pair, return it; otherwise generate and persist a new one. Code generation should use a deterministic approach (e.g., HMAC of mentorId+orgId+secret) or a UUID stored on first creation — choose based on whether auditability of the generation algorithm matters. `buildReferralUrl(code)` constructs the deep-link URI using the app's registered URI scheme and must produce URLs that pass through common link shorteners and social media platforms without truncation.
`invalidateCode` and `rotateCode` must update the repository atomically to prevent a window where an old code is invalid but no new code exists.
Responsibilities
- Generate deterministic or UUID-based referral codes per peer mentor
- Persist codes in Supabase with mentor and organisation associations
- Construct shareable referral URLs with deep-link scheme
- Invalidate or rotate codes if the mentor account is deactivated
Interfaces
getOrCreateReferralCode(mentorId, orgId)
buildReferralUrl(code)
invalidateCode(mentorId)
rotateCode(mentorId)
validateCode(code)
getMentorByCode(code)
Relationships
Related Data Entities (2)
Data entities managed by this component