Recruitment Attribution Repository
Component Detail
Description
Persists and queries recruitment funnel events in Supabase. Records click events, pending signups, and confirmed registrations with full attribution metadata linking new members to their referring peer mentor.
recruitment-attribution-repository
Summaries
The Recruitment Attribution Repository is the intelligence engine behind the referral program's measurable business impact. It captures every step of the member acquisition funnel — from the first link tap through to confirmed registration — giving leadership a real-time, auditable record of which peer mentors are driving growth. This data directly powers mentor recognition, informs incentive program design, and provides the evidence base for calculating referral program ROI. Accurate attribution is also a compliance requirement if referral bonuses or rewards are offered, making this component essential for both business development and organisational governance.
This is a medium-complexity backend component with a multi-event data model that touches several stages of the onboarding funnel, creating integration dependencies with the onboarding screens, membership verification service, and the mentor dashboard. Delivery sequencing matters: the click and conversion event insertions must be available before QA can test the end-to-end referral flow. Aggregation queries (countConfirmedByMentor, getConversionFunnel) should be performance-tested against realistic data volumes early, as slow dashboard queries are a common source of late-stage rework. Plan for a dedicated testing sprint that exercises the full funnel from click to confirmed attribution across both iOS and Android.
This repository encapsulates all Supabase DML and query operations for the recruitment_attributions table, which stores heterogeneous event types (click, pending, confirmed) in a single table using a discriminator pattern. insertClickEvent and insertConversionEvent both write to this table with differing metadata payloads — consider using a JSONB metadata column to avoid sparse nullable columns. confirmAttribution performs a status update that should be idempotent and guarded against double-confirmation via a CHECK constraint or optimistic locking. The getConversionFunnel method requires a multi-step aggregation (clicks → pending → confirmed) and should be implemented as a Postgres function or view to keep the Dart client logic thin.
Index on (mentor_id, created_at) for time-range queries and (code, status) for funnel rollups.
Responsibilities
- Insert referral click and conversion events
- Query attribution records by mentor, organisation, or date range
- Aggregate conversion counts for dashboard display
- Mark attribution records as confirmed after membership verification
Interfaces
insertClickEvent(code, metadata)
insertConversionEvent(code, newMemberId)
confirmAttribution(attributionId)
getByMentor(mentorId)
getByOrganisation(orgId)
countConfirmedByMentor(mentorId)
getConversionFunnel(mentorId)
Relationships
Dependents (3)
Components that depend on this component
Related Data Entities (1)
Data entities managed by this component