Badge BLoC
Component Detail
Description
Flutter BLoC state management for badge-related UI state including loading earned badges, handling badge earn events, and managing badge detail modal state. Integrates with the badge repository and reacts to activity-save events to refresh badge state.
badge-bloc
Summaries
The Badge BLoC is the coordination layer that brings the badge recognition experience to life in the mobile app. It ensures peer mentors see their achievements load quickly, receive immediate in-app celebrations when they earn new badges, and can explore badge details without friction. A smooth, responsive badge experience directly increases the motivational impact of the recognition system — when earning a badge feels instant and special, mentors are more likely to remain engaged. This component is essential to delivering the emotional payoff that makes the platform's recognition model effective and distinguishable from purely transactional tracking tools.
Medium complexity mobile component with dependencies on badge-repository and badge-definition-repository, both of which are blocking prerequisites. The BLoC must handle four distinct state transitions (loading, loaded, earned, error) plus modal state, making thorough state-machine testing essential — budget time for both unit tests on the BLoC logic and widget tests on downstream UI reactions. A key scheduling risk is the badge-earned event integration: the trigger mechanism (likely from an activity-save response or push notification) must be defined and agreed across mobile and backend teams before implementation begins. Plan for cross-team alignment session early in the sprint to avoid mid-delivery interface mismatches.
Implements Flutter BLoC pattern (bloc/cubit library) managing badge UI state across two data sources: badge-repository (earned badges) and badge-definition-repository (all available badge definitions). Events map to: LoadBadges triggers async fetch and emits BadgesLoaded or BadgesError; BadgeEarned appends to earned list and triggers celebration overlay; ShowBadgeDetail/DismissBadgeDetail toggle modal state. State shape: BadgesLoaded carries both earned List
Ensure bloc is scoped to the peer mentor session and disposed on logout to prevent stale state across user switches.
Responsibilities
- Load and cache earned badges for current peer mentor
- React to badge earned events and trigger celebration overlay
- Manage badge detail modal open/close state
- Handle error and loading states for badge data
Interfaces
LoadBadges(String peerMentorId)
BadgeEarned(EarnedBadge badge)
ShowBadgeDetail(BadgeDefinition badge)
DismissBadgeDetail()
BadgesLoaded(List<EarnedBadge> earned, List<BadgeDefinition> all)
BadgesError(String message)
Relationships
Dependencies (2)
Components this component depends on
Related Data Entities (2)
Data entities managed by this component