Milestone Detection Service
Component Detail
Description
Evaluates a peer mentor's aggregated stats against a predefined set of milestone thresholds (e.g., first session, 10 sessions, 50 hours, 100 people helped) to determine which milestones have been newly achieved in the current period. Returns ordered lists of unlocked and in-progress milestones.
milestone-detection-service
Summaries
The Milestone Detection Service transforms raw mentoring activity data into meaningful achievement recognition, directly driving peer mentor motivation and long-term platform retention. By automatically surfacing milestones such as a mentor's first session, tenth session, or fiftieth hour of service, the platform creates personalised reward moments that competitors cannot replicate without equivalent data depth. This recognition layer reduces mentor churn, increases session frequency, and strengthens the emotional bond between mentors and the platform — translating directly into a healthier supply of mentors and improved outcomes for the people they support. The accessibility-aware milestone descriptions also ensure compliance with inclusive design standards, reducing legal exposure and broadening the addressable user base across diverse ability groups.
The Milestone Detection Service carries medium implementation complexity and must be delivered after the Annual Summary Repository is stable, since it depends on aggregated stats being consistently structured. The team should allocate time for defining and validating the full milestone threshold matrix with product stakeholders before development begins, as threshold changes post-launch will require coordinated backend and mobile releases. Testing must cover edge cases including first-ever milestones, milestones achieved simultaneously in a single period, and regression scenarios where previously unlocked milestones must not re-trigger. Accessibility label generation for multiple locales adds an internationalisation dependency that should be scoped explicitly.
Plan for an integration test pass on both iOS and Android execution contexts, since the service runs in both environments.
The Milestone Detection Service is a pure business-logic layer with no direct I/O — it receives an AnnualSummary domain object and returns ordered Milestone and MilestoneProgress lists, making it straightforward to unit test in isolation. The detectMilestones interface performs threshold comparison against a predefined configuration set; consider externalising the threshold definitions to a JSON or database-driven config to avoid redeployment for threshold changes. getNewMilestones delegates to annual-summary-repository to fetch the current period's stats before comparison, introducing a Future-based async boundary that must propagate correctly through the BLoC layer. getMilestoneAccessibilityLabel should integrate with the app's existing localisation infrastructure (e.g., Flutter's intl package) to return locale-correct strings.
Ranking logic for narrative ordering should be deterministic and tested against tied-significance scenarios to ensure stable UI ordering.
Responsibilities
- Compare current period stats against milestone thresholds
- Detect newly unlocked milestones versus previously held ones
- Rank milestones by significance for narrative ordering
- Generate accessible milestone descriptions in the user's language
Interfaces
detectMilestones(summary: AnnualSummary): List<Milestone>
getNewMilestones(mentorId: String, period: SummaryPeriod): Future<List<Milestone>>
getInProgressMilestones(summary: AnnualSummary): List<MilestoneProgress>
getMilestoneAccessibilityLabel(milestone: Milestone): String
Relationships
Related Data Entities (2)
Data entities managed by this component