Achievement Badges & Recognition
Feature Detail
Description
This feature implements a structured recognition system that awards digital badges and titles to peer mentors and coordinators based on quantifiable milestones, tenure, and special contributions. Badges cover categories such as activity volume, consecutive months of participation, assignment completion rates, and organisational awards like Coordinator of the Year. The system provides a dedicated Achievements screen where users can view earned and locked badges, track progress toward the next milestone, and understand the criteria for each recognition tier.
Analysis
Recognition programmes have a well-documented effect on volunteer engagement and longevity. For organisations that rely entirely on unpaid peer mentors, a cost-free digital badge system delivers motivational value that would otherwise require expensive material rewards. The Coordinator of the Year award and similar organisational recognitions give local coordinators a tool to publicly celebrate top performers, strengthening community cohesion within each association. Milestone badges also serve a practical function for Blindeforbundet specifically, where the number of completed assignments determines honorarium thresholds; surfacing this progress transparently reduces coordinator workload and prevents disputes about eligibility.
Badge definitions are stored as configuration data in the badge_repository table, allowing administrators to add or modify badge criteria without a code deployment. The Achievement Service evaluates badge eligibility as a background job triggered after each activity save and after period-end calculations. Badge award events emit a notification via the Push Notification Service so users are informed immediately. The UI uses Flutter's AnimatedSwitcher and custom painter classes to render badge illustrations with locked/unlocked states and progress indicators. The system must support per-organisation badge sets so that HLF's certification-linked badges and Blindeforbundet's assignment-count badges can coexist without coupling. All badge images must meet contrast requirements and include descriptive alt text for screen reader compatibility.
Dependencies
Definition of Done
Components (4)
User Stories (13)
As a As a user
I want I want to receive a push notification immediately when I earn a new badge
So that So that I am informed of my achievement in the moment it happens, reinforcing the positive impact of my contribution even when I am not actively using the app
- Given a user completes an activity that crosses a badge threshold, when the Achievement Service background job runs, then a push notification is dispatched within 60 seconds
- Given a push notification is sent for a badge award, when the user taps the notification, then the app opens directly to the Achievements screen with the newly unlocked badge visible
- Given the user has disabled push notifications for the app, when a badge is awarded, then no push notification is sent but the badge is still recorded as earned in the database
- +2 more
As a As a user
I want I want to tap on any badge to read the full unlock criteria and requirements for that recognition tier
So that So that I understand exactly what behaviours or milestones are being incentivised and can plan my activities accordingly
- Given a user taps on any badge (earned or locked), when the detail view opens, then the badge name, category, full description, and specific unlock criteria are displayed
- Given a badge has a numeric threshold, when the detail view is shown, then the exact number required (e.g. '15 completed assignments') is stated clearly
- Given an administrator updates badge criteria in the repository, when a user views the badge detail, then the updated criteria text is shown without requiring an app update
- +2 more
As a As a user
I want I want to see only the badges relevant to my organisation, with criteria and thresholds tailored to my organisation's programme
So that So that the recognition system reflects the real structure of my organisation's volunteer programme rather than showing irrelevant badges from other organisations
- Given a peer mentor belongs to HLF, when they open the Achievements screen, then only HLF-scoped badges are displayed and no Blindeforbundet assignment-count badges appear
- Given a peer mentor belongs to Blindeforbundet, when they open the Achievements screen, then only Blindeforbundet-scoped badges appear including the 3rd and 15th assignment milestone badges
- Given a user is a member of multiple organisations, when they switch their active organisation context, then the Achievements screen refreshes and displays the badge catalogue for the newly active organisation
- +2 more
As a As a user
I want I want to receive a push notification immediately when I earn a new badge
So that So that I am informed of my achievement in the moment it happens, reinforcing the positive impact of my contribution even when I am not actively using the app
- Given a user completes an activity that crosses a badge threshold, when the Achievement Service background job runs, then a push notification is dispatched within 60 seconds
- Given a push notification is sent for a badge award, when the user taps the notification, then the app opens directly to the Achievements screen with the newly unlocked badge visible
- Given the user has disabled push notifications for the app, when a badge is awarded, then no push notification is sent but the badge is still recorded as earned in the database
- +2 more
As a As a user
I want I want to tap on any badge to read the full unlock criteria and requirements for that recognition tier
So that So that I understand exactly what behaviours or milestones are being incentivised and can plan my activities accordingly
- Given a user taps on any badge (earned or locked), when the detail view opens, then the badge name, category, full description, and specific unlock criteria are displayed
- Given a badge has a numeric threshold, when the detail view is shown, then the exact number required (e.g. '15 completed assignments') is stated clearly
- Given an administrator updates badge criteria in the repository, when a user views the badge detail, then the updated criteria text is shown without requiring an app update
- +2 more
As a As a Coordinator
I want I want to be awarded organisation-level recognition badges such as Coordinator of the Year and view them prominently in my Achievements screen
So that So that my exceptional contributions to the organisation are formally recognised and I can share this recognition within my professional community
- Given an administrator awards a Coordinator of the Year badge to a coordinator, when the award is processed, then the badge appears in the coordinator's Achievements screen under 'Organisational Awards'
- Given a coordinator is awarded an organisational badge, when the Achievement Service emits the award event, then the Push Notification Service dispatches an immediate notification with the award name
- Given a coordinator views their Coordinator of the Year badge, when they tap it, then the detail view shows the award year, the criteria or citation associated with the award, and the awarding organisation
- +2 more
As a As a user
I want I want to see only the badges relevant to my organisation, with criteria and thresholds tailored to my organisation's programme
So that So that the recognition system reflects the real structure of my organisation's volunteer programme rather than showing irrelevant badges from other organisations
- Given a peer mentor belongs to HLF, when they open the Achievements screen, then only HLF-scoped badges are displayed and no Blindeforbundet assignment-count badges appear
- Given a peer mentor belongs to Blindeforbundet, when they open the Achievements screen, then only Blindeforbundet-scoped badges appear including the 3rd and 15th assignment milestone badges
- Given a user is a member of multiple organisations, when they switch their active organisation context, then the Achievements screen refreshes and displays the badge catalogue for the newly active organisation
- +2 more
As a As a user
I want I want to open the Achievements screen and see all my earned and locked badges organised by category
So that So that I can understand the full scope of recognition available and feel pride in the milestones I have already reached
- Given a peer mentor or coordinator opens the Achievements screen, when the screen loads, then all badge categories for their organisation are displayed with at least one badge visible per category
- Given a user has earned a badge, when they view the Achievements screen, then that badge appears in an unlocked, full-colour animated state distinct from locked badges
- Given a user has not yet earned a badge, when they view the Achievements screen, then that badge is displayed in a greyed-out locked state
- +3 more
As a As a user
I want I want to see a progress indicator on each locked badge showing how close I am to earning it
So that So that I know exactly what actions will unlock the next recognition tier and feel motivated to continue contributing
- Given a user views a locked badge, when the Badge Widget renders, then a circular progress ring shows current progress as a percentage toward the unlock threshold
- Given a user completes an activity that advances their progress, when they return to the Achievements screen, then the progress ring reflects the updated value
- Given a Blindeforbundet user is at 14 completed assignments, when they view the assignment-count badge, then the progress ring shows 14/15 and the threshold label is visible
- +2 more
As a As a user
I want I want all badge illustrations, progress indicators, and achievement descriptions to be fully accessible via screen reader
So that So that visually impaired peer mentors and coordinators can experience the recognition programme on equal terms with sighted users
- Given a user navigates the Achievements screen with VoiceOver enabled, when focus moves to a badge, then the screen reader announces the badge name, its locked or unlocked state, and the progress value if applicable
- Given a badge has a progress ring, when a screen reader user focuses on it, then the accessible label includes both the current value and the target threshold (e.g. '7 of 15 assignments completed')
- Given the badge unlock animation plays, when it completes, then screen reader focus is not disrupted and the newly unlocked state is announced
- +2 more
As a As a user
I want I want to open the Achievements screen and see all my earned and locked badges organised by category
So that So that I can understand the full scope of recognition available and feel pride in the milestones I have already reached
- Given a peer mentor or coordinator opens the Achievements screen, when the screen loads, then all badge categories for their organisation are displayed with at least one badge visible per category
- Given a user has earned a badge, when they view the Achievements screen, then that badge appears in an unlocked, full-colour animated state distinct from locked badges
- Given a user has not yet earned a badge, when they view the Achievements screen, then that badge is displayed in a greyed-out locked state
- +3 more
As a As a user
I want I want to see a progress indicator on each locked badge showing how close I am to earning it
So that So that I know exactly what actions will unlock the next recognition tier and feel motivated to continue contributing
- Given a user views a locked badge, when the Badge Widget renders, then a circular progress ring shows current progress as a percentage toward the unlock threshold
- Given a user completes an activity that advances their progress, when they return to the Achievements screen, then the progress ring reflects the updated value
- Given a Blindeforbundet user is at 14 completed assignments, when they view the assignment-count badge, then the progress ring shows 14/15 and the threshold label is visible
- +2 more
As a As a user
I want I want all badge illustrations, progress indicators, and achievement descriptions to be fully accessible via screen reader
So that So that visually impaired peer mentors and coordinators can experience the recognition programme on equal terms with sighted users
- Given a user navigates the Achievements screen with VoiceOver enabled, when focus moves to a badge, then the screen reader announces the badge name, its locked or unlocked state, and the progress value if applicable
- Given a badge has a progress ring, when a screen reader user focuses on it, then the accessible label includes both the current value and the target threshold (e.g. '7 of 15 assignments completed')
- Given the badge unlock animation plays, when it completes, then screen reader focus is not disrupted and the newly unlocked state is announced
- +2 more