Personal Statistics Service
Component Detail
Description
Fetches and processes individual peer mentor statistics for the personal stats view. Provides the data foundation required for Phase 4 Spotify Wrapped gamification by storing structured contribution history accessible for future wrapped/gamification queries.
personal-stats-service
Summaries
The Personal Statistics Service delivers individual peer mentor performance data directly to mentors via the mobile app, giving them clear visibility into their own contributions, hours logged, and reimbursements earned. This transparency drives mentor engagement and retention by making their impact tangible and recognized. Crucially, this service is architected to serve as the data foundation for the planned Phase 4 Spotify Wrapped gamification feature — a high-impact engagement initiative that transforms raw contribution history into shareable, celebratory year-in-review summaries. By investing in this service now with gamification compatibility built in, the organization avoids costly rework later and accelerates time-to-market for the engagement feature that directly supports mentor recruitment and retention goals.
The Personal Statistics Service has medium complexity and is scoped entirely to the mobile execution context. It depends on two other components — stats-repository and stats-cache-manager — both of which must be completed before this service can be fully tested end-to-end. The 15-minute cache integration reduces load testing concerns but requires coordination with the cache invalidation strategy. Key delivery risk: the contribution history data structure must be designed with Phase 4 gamification requirements in mind now, or a refactor will be required later.
Recommend scheduling a brief cross-team alignment on gamification data shape before implementation begins. Testing scope includes unit tests for period filtering logic, integration tests against Supabase views, and cache hit/miss verification. No backend work required beyond Supabase view readiness.
Personal Statistics Service is a mobile-layer service component that orchestrates calls to stats-repository and stats-cache-manager to serve a single mentor's statistical profile. It exposes five methods: getPersonalStats (aggregated totals with period filter), getPersonalMonthlyActivitySeries (time-series for bar charts), getPersonalActivityTypeBreakdown (categorical split), getContributionHistory (multi-year history for gamification), and invalidatePersonalCache (explicit cache bust). The cache key must encode mentorId + StatsPeriodFilter hash. ContributionHistory return type should be forward-compatible with Phase 4 gamification — model it as a structured list of yearly summaries with monthly breakdowns.
All four stat fetch methods should route through cache-manager before hitting the repository. Data models consumed: activity and peer-mentor tables via Supabase pre-aggregated views.
Responsibilities
- Fetch personal activity totals, hours, and reimbursements for a single mentor
- Build monthly activity series for personal bar chart
- Expose contribution data structure compatible with Phase 4 gamification
- Apply 15-minute cache for personal stats queries
Interfaces
getPersonalStats(String mentorId, StatsPeriodFilter filter) → Future<PersonalStatsSummary>
getPersonalMonthlyActivitySeries(String mentorId, DateRange period) → Future<List<MonthlyStatPoint>>
getPersonalActivityTypeBreakdown(String mentorId, DateRange period) → Future<List<ActivityTypeBreakdown>>
getContributionHistory(String mentorId, int years) → Future<ContributionHistory>
invalidatePersonalCache(String mentorId)
Relationships
Dependencies (2)
Components this component depends on