🏠 Overview › ✅ Implementation Tasks ›✅ epic-membership-recruitment-peer-mentor-ui-task-014

Document referral UI components and Riverpod providers

epic-membership-recruitment-peer-mentor-ui-task-014 — Write developer documentation for ReferralCodeScreen, RecruitmentStatsWidget, and NewMemberOnboardingScreen covering component responsibilities, Riverpod provider wiring, deep-link token validation logic, attribution submission flow, and accessibility implementation notes. Include usage examples for embedding the stats widget.

medium priority low complexity documentation pending documentor Tier 7

Acceptance Criteria

ReferralCodeScreen documentation covers its full responsibility: displaying the peer mentor's unique referral code, sharing via native share sheet, and deep-link token parsing on entry.
RecruitmentStatsWidget documentation includes all props/parameters, how to embed it within a parent screen, and the Riverpod provider it reads from.
NewMemberOnboardingScreen documentation describes the step flow, which Riverpod notifier handles state transitions, and how attribution is submitted at the final step.
Deep-link token validation logic is documented with example URIs, expected token format, error states (expired token, invalid token, already-used token), and how validation failures surface in the UI.
Attribution submission flow is documented end-to-end: token extraction → API call → SubmissionOutcome handling → UI feedback.
Accessibility implementation notes cover semantic labels for the referral code text field (screen-reader-readable digit-by-digit or as a unit), contrast ratios, and focus order.
At least one complete Dart code snippet demonstrates embedding RecruitmentStatsWidget in a host screen with provider scope.
All documented provider names match the actual implementation delivered in task-013.
Documentation is written in English and stored in the agreed location (e.g., `docs/` or in-file dartdoc comments).

Technical Requirements

frameworks
Flutter
Riverpod
data models
ReferralCode
RecruitmentStats
AttributionSubmission
performance requirements
Documentation must accurately reflect actual provider dependency graph — no stale references.
security requirements
Document that referral tokens must never be logged or persisted in plaintext beyond the validation step.
Note that deep-link URIs must be validated server-side; client-side token parsing is UI-only.
ui components
ReferralCodeScreen
RecruitmentStatsWidget
NewMemberOnboardingScreen

Execution Context

Execution Tier
Tier 7

Tier 7 - 84 tasks

Can start after Tier 6 completes

Implementation Notes

Since this task directly follows task-013, the documentation author should read the implemented source files before writing — do not rely on memory or earlier specs. Use Dart's `///` dartdoc format for in-file documentation on public classes and methods; use a markdown file in `docs/referral/` for the higher-level architectural narrative and embedding guide. Pay special attention to documenting the Riverpod provider graph: list each provider by name, its type (Provider, StateNotifierProvider, FutureProvider, etc.), what it exposes, and which widget consumes it. For the deep-link section, include a sequence diagram (ASCII or Mermaid) showing: OS hands URI → Flutter router → ReferralCodeScreen init → token extraction → validation API call → result routing.

Accessibility notes should cross-reference WCAG 2.2 AA criteria (1.4.3 contrast, 1.3.1 info and relationships, 4.1.2 name/role/value) so future developers know which standard is being targeted.

Testing Requirements

No automated tests for documentation itself. However, the documenter must manually verify all code snippets compile without errors in the project context (run `flutter analyze` on any added Dart snippet files).

Verify that all provider names referenced in docs exist in the codebase via a grep check. Peer review by one other developer to confirm accuracy and completeness before merge.

Component
Referral Code Screen
ui medium
Dependencies (1)
Write Flutter widget tests for ReferralCodeScreen, RecruitmentStatsWidget, and NewMemberOnboardingScreen covering rendering, user interactions (copy, share, form submit), loading/error states, and Riverpod provider mocking. Add integration tests for the deep-link → onboarding → attribution submission flow. epic-membership-recruitment-peer-mentor-ui-task-013
Epic Risks (3)
medium impact medium prob technical

QR codes rendered at the minimum 200×200 size may fail to scan under typical indoor lighting conditions on older or lower-resolution phone cameras, causing recruitment moments to fail when a peer mentor shows the screen to a prospective member.

Mitigation & Contingency

Mitigation: Set the default QR render size to 260×260 logical pixels (not the 200px minimum) and apply a high-contrast white module background. Test scan reliability on at minimum three physical devices (budget Android, mid-range Android, iPhone SE) before marking the screen as done.

Contingency: If scan reliability remains an issue, add a 'Enlarge QR' full-screen mode triggered by tapping the code, and ensure the text referral URL with copy-to-clipboard is always visible as a fallback sharing method.

high impact medium prob integration

The onboarding screen submits attribution and then hands off to an external membership registration URL (HLF's Dynamics portal or similar). If the external URL is unavailable, changes its format, or requires authentication the new member does not have, the conversion funnel is broken at its final step.

Mitigation & Contingency

Mitigation: Confirm the external registration URL and its expected query parameters with HLF's portal team before implementing the handoff. Record the pending_signup attribution event before launching the URL so data is not lost if the external site fails. Display a fallback message with contact information if the URL launch fails.

Contingency: If the external membership URL is not available at feature launch, implement a temporary form that collects name and email and stores a pending_member record in Supabase, allowing coordinators to manually complete registration while the integration is finalised.

low impact medium prob integration

Embedding the RecruitmentStatsWidget on the peer mentor home screen may conflict with existing layout components (activity summary, badge shelf), causing overflow or requiring a redesign of the home screen that is outside this epic's scope.

Mitigation & Contingency

Mitigation: Design the widget as a horizontally constrained card with a maximum height of 96dp so it can be inserted into any vertical list without overflow. Coordinate with the home screen's existing layout owners before starting the embedding task.

Contingency: If home screen embedding creates unacceptable layout conflicts, defer embedding to a separate home-screen redesign task and make the widget accessible only via the dedicated ReferralCodeScreen for the initial release.

Quick Links
All Tasks Execution Plan