Referral Code Repository
Component Detail
Description
Handles all Supabase CRUD operations for the referral_codes table. Ensures each peer mentor has at most one active code per organisation and supports lookup by code string for deep-link resolution.
referral-code-repository
Summaries
The Referral Code Repository is the foundational data layer that makes the peer mentorship referral program trustworthy and scalable. By enforcing business rules — specifically that each mentor holds at most one active code per organisation — it prevents duplicate attribution errors that could undermine trust with both mentors and administrators. Accurate referral tracking directly supports mentor recognition programs, incentive schemes, and membership growth reporting. Without this integrity layer, incorrect attributions could damage mentor relationships and erode confidence in the platform's fairness, representing a significant retention risk for your mentor community.
This is a low-complexity backend data component with a narrow, well-defined scope, making it a reliable early deliverable in the sprint. It has no external service dependencies, so it is not on the critical path for other teams and can be built and tested in isolation. The primary delivery risk is ensuring the unique-active-code constraint is enforced at the database level as well as the application level — a brief schema review with the DBA should confirm this. Integration testing should cover edge cases such as concurrent code creation attempts and code rotation flows, which require coordinated test data setup with the attribution component.
This component is a pure Supabase data access object targeting the referral_codes table. All five interface methods map directly to Supabase client calls with typed return values. The uniqueness invariant (one active code per mentor+org pair) must be enforced via a PostgreSQL unique partial index on (mentor_id, org_id) WHERE status = 'active', not only in application logic. The findByCode method supports O(1) deep-link resolution and should be backed by a btree index on the code column.
Deactivation flows (rotate, invalidate) should use database transactions to atomically update status and timestamp fields. No caching layer is currently defined, but getActiveCode is a hot path during QR display and may warrant a short-lived in-memory cache at the service layer.
Responsibilities
- Insert new referral code records
- Fetch active code for a given mentor and organisation
- Update code status (active, invalidated, rotated)
- Lookup mentor identity from an inbound code string
Interfaces
createCode(mentorId, orgId, code)
getActiveCode(mentorId, orgId)
findByCode(code)
deactivateCode(mentorId, orgId)
listCodesByOrganisation(orgId)
Relationships
Used Integrations (1)
External integrations and APIs this component relies on