Recruitment Stats Widget
Component Detail
Description
A reusable card widget showing the peer mentor's recruitment summary — total invites sent, successful conversions, and pending signups. Embedded in the referral screen and the peer mentor home screen.
recruitment-stats-widget
Summaries
The Recruitment Stats Widget provides peer mentors with immediate, visible evidence that their referral activity is generating results — a critical driver of continued participation in the growth programme. By surfacing total invites sent, confirmed conversions, and pending signups in a concise card format embedded across multiple screens, it creates a persistent motivational signal that encourages ongoing recruitment behaviour without requiring additional prompts. From a business perspective, this visibility loop directly supports the referral programme's conversion targets: mentors who can see their impact are more likely to continue sharing.
The widget's reuse across the referral screen and home screen maximises the frequency of this reinforcement at minimal additional development cost.
This is a low-complexity, self-contained Flutter widget with a single dependency on the recruitment-attribution-repository. Its reusable nature means it delivers value in two locations — the referral screen and the home screen — from a single implementation effort, improving delivery efficiency. The main scheduling consideration is ensuring the recruitment-attribution-repository is available before integration testing of either parent screen begins. `onViewDetailsTapped()` implies a navigation target (detailed recruitment history list) that must be scoped and built as a separate deliverable — clarify whether this is in-scope for the same sprint.
Unit tests should cover the `formatConversionRate()` calculation with zero-division edge cases. No native device testing is required; standard widget testing on emulator is sufficient.
Implemented as a Flutter StatelessWidget (or lightweight StatefulWidget if local loading state is needed), this card widget calls `loadStats(mentorId)` on mount to fetch a RecruitmentAttributionSummary from the recruitment-attribution-repository, then renders three numeric values: total shares, confirmed conversions, and either a computed conversion rate via `formatConversionRate(invited, converted)` or a pending count. The `formatConversionRate()` helper must guard against division by zero when invited is 0. `onViewDetailsTapped()` triggers navigation to the recruitment history list screen — pass the mentorId as a route argument. The widget should expose a loading skeleton state for the async fetch and an error state with a retry action.
Because it is embedded in two parent screens, keep its external interface minimal and avoid internal navigation side effects that could conflict with parent routing contexts.
Responsibilities
- Display total referral link shares
- Show confirmed new member conversions
- Render conversion rate or pending count
- Link to detailed recruitment history list
Interfaces
build(context)
loadStats(mentorId)
onViewDetailsTapped()
formatConversionRate(invited, converted)
Relationships
Related Data Entities (2)
Data entities managed by this component
Used Integrations (1)
External integrations and APIs this component relies on