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

Scaffold ReferralCodeScreen layout and routing

epic-membership-recruitment-peer-mentor-ui-task-001 — Create the ReferralCodeScreen widget with basic scaffold, app bar, and placeholder content areas. Register the route in the app router and ensure it is accessible from the peer mentor home screen. Apply design token system for colors, typography, and spacing.

high priority low complexity frontend pending frontend specialist Tier 0

Acceptance Criteria

A ReferralCodeScreen StatelessWidget (or ConsumerWidget if Riverpod state is needed) exists at lib/features/recruitment/presentation/screens/referral_code_screen.dart
The screen renders a Scaffold with an AppBar whose title uses the organisation label system for 'My Referral Code' (or equivalent localised key)
The screen body contains clearly named placeholder sections: referral code display area, share actions area, and stats/attribution area — each as a comment or empty Container with a semantic label
A GoRouter route for /referral-code (or the agreed path) is registered in the app router configuration file and resolves to ReferralCodeScreen
The route is role-gated: only users with the peer_mentor role can access it — attempting to navigate to it as a coordinator or admin redirects to the home screen or a not-authorised screen
The peer mentor home screen contains a navigation entry (card, list tile, or button) that pushes /referral-code
All colors, typography styles, and spacing values use design token constants (no hard-coded hex values or raw pixel values)
The screen passes flutter analyze with zero errors and zero warnings
The screen is accessible: AppBar title has a semantics label, back button has a tooltip, content areas have semantic roles
Widget test verifies the screen renders without throwing and the AppBar title text is present

Technical Requirements

frameworks
Flutter
GoRouter (existing app router)
Riverpod (flutter_riverpod) for role-based guard if using existing auth provider
Design token system (existing token constants)
apis
Existing auth/role provider (to read current user role for route guard)
Organisation labels system (for dynamic screen title)
data models
UserRole (enum, to enforce peer_mentor guard)
OrganisationLabels (for title string)
performance requirements
Screen must reach first paint within one frame after navigation (no blocking futures in build())
Placeholder containers must have zero computational cost — no animations or heavy widgets in scaffold phase
security requirements
Route guard must be enforced at the GoRouter redirect level — not only in the UI — so direct URI navigation is also blocked
Screen must not display any referral code or personal data in this scaffold task — placeholder text only
ui components
Scaffold
AppBar (using existing app bar widget or pattern)
Placeholder content Containers with semantic labels
Navigation entry on peer mentor home screen (AppCard or ListTile following existing pattern)

Execution Context

Execution Tier
Tier 0

Tier 0 - 440 tasks

Implementation Notes

Follow the exact file and class naming convention used by other screens in the project (e.g. activity_detail_screen.dart → ActivityDetailScreen). Register the route in the same router file as all other routes — do not create a separate router file for recruitment. For the role guard, use GoRouter's redirect callback pattern already established in the project rather than implementing a new guard mechanism.

Apply the existing AppBar widget (or pattern) used on other peer mentor screens so the back-button behaviour and title style are consistent. The placeholder content areas should use const SizedBox.shrink() or a named placeholder widget — not empty Column/Row — so they are easy to find and replace in subsequent tasks. Confirm the design token import path matches the project's existing pattern before referencing token constants.

Testing Requirements

Write a widget test at test/features/recruitment/presentation/screens/referral_code_screen_test.dart. Test cases: (1) ReferralCodeScreen renders without throwing when pumped with a minimal ProviderScope containing required provider overrides, (2) AppBar contains the expected title text (use find.text() or find.byWidgetPredicate for semantics label), (3) navigating to /referral-code as a peer_mentor role does not redirect, (4) navigating to /referral-code as a coordinator role redirects away (GoRouter redirect test). Use flutter_test with testWidgets(). Mock auth and role providers via ProviderScope overrides.

Do not test placeholder content areas beyond confirming the screen does not throw — content will be tested in later tasks.

Component
Referral Code Screen
ui medium
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