Referral Code Screen
Component Detail
Description
Displays the peer mentor's unique referral QR code and shareable link in a prominent, easy-to-share format. Provides a one-tap action to open the system share sheet and shows a summary of past recruitment activity.
referral-code-screen
Summaries
The Referral Code Screen is the primary growth mechanism for expanding the peer mentor programme organically. By giving each peer mentor a personalised QR code and shareable link in a frictionless, tap-to-share interface, the platform transforms existing participants into active recruiters. This directly reduces the cost of new member acquisition compared to paid channels, while ensuring recruits arrive with an established mentor relationship already in place — improving their onboarding success rate. The recruitment activity summary visible on the screen provides immediate positive reinforcement for sharing behaviour, encouraging repeat engagement with the referral feature and compounding the programme's growth flywheel effect over time.
This is a medium-complexity mobile screen with three direct dependencies: the referral-code-service (backend), qr-code-generator (library integration), and share-sheet-bridge (native plugin). All three must be completed or available before this screen can be fully integrated and tested. The QR code rendering and share-sheet invocation require device testing across iOS and Android — emulators are insufficient for share-sheet validation. Plan a dedicated mobile QA pass.
The `refreshReferralData()` function introduces a network dependency that must be handled gracefully in offline scenarios. Coordinate with backend on the referral URL format before front-end implementation begins to avoid rework. Recruitment attribution display requires the attribution repository to be populated, so end-to-end testing needs the full referral flow instrumented.
Built as a Flutter StatefulWidget, this screen composes three primary elements: a QR code widget rendered by qr-code-generator from the URL returned by referral-code-service, a copy-to-clipboard action on the referral link, and a share-sheet trigger via the share-sheet-bridge abstraction over the Flutter Share plugin. `onShareTapped()` calls the bridge with a pre-formatted message string containing the referral URL. `displayQrCode(referralUrl)` wraps the QR library call, handling null/loading states. `showRecruitmentCount(count)` delegates to the recruitment-stats-widget for consistent rendering.
`refreshReferralData()` triggers a re-fetch from referral-code-service and rebuilds the widget tree. Data models consumed: referral-code (for URL and code string) and recruitment-attribution (for conversion count display). Ensure the referral URL is deep-link compatible for correct app routing on recipient devices.
Responsibilities
- Render QR code from referral URL
- Display shareable referral link with copy-to-clipboard action
- Trigger system share sheet via Flutter Share plugin
- Show count of successful recruitments attributed to this peer mentor
Interfaces
build(context)
onShareTapped()
onCopyLinkTapped()
refreshReferralData()
displayQrCode(referralUrl)
showRecruitmentCount(count)
Relationships
Dependencies (3)
Components this component depends on
Used Integrations (1)
External integrations and APIs this component relies on