Referral Attribution Service
Component Detail
Description
Tracks the full conversion funnel from referral link click through to completed membership registration. Associates each new member signup with the originating peer mentor and records the event for dashboard reporting and badge criteria evaluation.
referral-attribution-service
Summaries
The Referral Attribution Service is the engine that converts peer mentor effort into measurable organisational outcomes. It tracks every step of the recruitment journey — from the moment a potential member clicks a referral link to the point they complete their membership registration — and ties that outcome back to the specific mentor who drove it. This closed-loop attribution is what makes the peer recruitment programme credible: it enables accurate recognition of high-performing mentors, supports evidence-based badge and reward decisions, and provides the programme with auditable data for funding reports and impact measurement. Without this service, recruitment incentives cannot be fairly administered, reducing mentor motivation and programme effectiveness.
This is the highest-complexity component in the referral feature set, as it coordinates across multiple domains: click event ingestion, registration confirmation matching, attribution persistence, and badge system notification. The matching step — linking a completed registration to a prior click event — is particularly sensitive and requires careful handling of edge cases such as delayed registrations, users clicking multiple referral links, or registration failures after attribution is recorded. It has a dual dependency on `recruitment-attribution-repository` and `badge-criteria-integration`, the latter of which may itself be partially out of scope for an initial release. Agree on a phased delivery plan: core click tracking and confirmation first, badge notification integration in a follow-on sprint.
The service implements a two-phase attribution model. Phase one: `recordReferralClick(code, metadata)` writes a pending attribution record to the repository, capturing timestamp, device metadata, and the resolved mentor+org from the code via `referral-code-service`. Phase two: `confirmRecruitment(code, newMemberId)` looks up the pending record by code, marks it confirmed, and links the new member's ID. This lookup must handle the case where no pending click record exists (e.g., direct app install without a click).
`notifyBadgeService(mentorId, eventType)` should be fire-and-forget with retry logic or queued via a message bus to avoid blocking the registration confirmation flow. `getConversionRate(mentorId)` derives click-to-registration ratio and should be computed at query time or cached — do not store as a mutable field to avoid stale data.
Responsibilities
- Record referral link click events with timestamp and device metadata
- Match completed registrations to originating referral codes
- Mark attribution as confirmed once membership registration is verified
- Expose attribution counts for badge criteria evaluation
- Notify badge service when a recruitment milestone is reached
Interfaces
recordReferralClick(code, metadata)
confirmRecruitment(code, newMemberId)
getAttributionsByMentor(mentorId)
getTotalRecruitments(mentorId)
getConversionRate(mentorId)
notifyBadgeService(mentorId, eventType)
Relationships
Dependencies (2)
Components this component depends on
Dependents (2)
Components that depend on this component
Related Data Entities (2)
Data entities managed by this component