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

Embed RecruitmentStatsWidget on peer mentor home screen

epic-membership-recruitment-peer-mentor-ui-task-007 — Add RecruitmentStatsWidget to the peer mentor role-specific home screen as a summary card. Ensure it is positioned correctly in the home screen layout and does not break existing home screen content. Widget must be gated behind a feature flag for controlled rollout.

medium priority low complexity frontend pending frontend specialist Tier 1

Acceptance Criteria

RecruitmentStatsWidget is rendered on the peer mentor home screen as a summary card section
The widget is positioned after existing primary home screen content (activity summary, assignments) and before secondary content
The widget is wrapped in a feature flag check — it renders only when the `recruitment_stats_home` feature flag is enabled
When the feature flag is disabled, no empty space or placeholder is left — the layout reflows as if the widget does not exist
Existing home screen widgets (activity summary, assignment count, etc.) continue to render correctly with the new widget present
No layout overflow or pixel overflow errors are introduced on the home screen
The widget card has a section title label (e.g., 'Your recruitment') above the stats row
Tapping the stats card (or a link within it) navigates to ReferralCodeScreen
Feature flag value is read from a Riverpod provider backed by Supabase remote config or a local config source
The widget meets WCAG 2.2 AA contrast requirements consistent with the rest of the home screen design

Technical Requirements

frameworks
Flutter
Riverpod
apis
Feature flag provider (internal Riverpod provider)
Supabase PostgreSQL 15 or remote config (feature flag source)
data models
assignment
performance requirements
Feature flag check must not add a loading state to the home screen — flag value must be synchronously available from cached config on screen load
RecruitmentStatsWidget on home screen uses the same cached provider data — no additional network call if already fetched
security requirements
Feature flag source must be server-authoritative — do not allow client-side override of feature flags
RLS still applies to underlying stats data regardless of feature flag state
ui components
RecruitmentStatsWidget (embedded as card)
Card or Container with section title
Feature flag conditional wrapper
InkWell or GestureDetector for tappable card navigation

Execution Context

Execution Tier
Tier 1

Tier 1 - 540 tasks

Can start after Tier 0 completes

Implementation Notes

Define a `featureFlagProvider` as an `AsyncNotifierProvider` or a simple `Provider` backed by a config service. For the home screen, use a conditional render pattern: `if (ref.watch(recruitmentStatsFlagProvider)) RecruitmentStatsWidget(mentorId: mentorId)`. Wrap the widget in a `Card` with a `ListTile`-style header showing 'Your recruitment' and an arrow icon to indicate tappability. Use `GestureDetector(onTap: () => context.push('/referral-code'))` around the card.

Keep the feature flag provider simple for now — a Supabase table lookup or a hardcoded value in a constants file is sufficient for controlled rollout.

Testing Requirements

Write widget tests using flutter_test with ProviderScope overrides. Test (1) RecruitmentStatsWidget renders on home screen when feature flag is enabled, (2) widget is absent from home screen widget tree when feature flag is disabled, (3) existing home screen widgets remain present in both flag states, (4) tapping the stats card navigates to ReferralCodeScreen. Use a mock feature flag provider to toggle the flag state in tests. Golden test the home screen layout in both flag-enabled and flag-disabled states to detect regressions.

Component
Recruitment Stats Widget
ui low
Dependencies (1)
Create the RecruitmentStatsWidget StatelessWidget displaying total shares, confirmed conversions, and pending signups. Wire it to a Riverpod provider consuming ReferralAttributionService. Show loading and empty states. Apply design token colors and typography. epic-membership-recruitment-peer-mentor-ui-task-005
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