Recognition Tier Service
Component Detail
Description
Manages named recognition tiers such as Coordinator of the Year and seasonal awards. Handles tier assignment logic, award period management, and exposure of tier data to profile and coordinator views.
recognition-tier-service
Summaries
The Recognition Tier Service powers high-prestige awards such as Coordinator of the Year, which are among the most motivating recognition signals an organisation can offer. By automating tier eligibility evaluation and award period management, this service removes manual administrative overhead from programme coordinators while ensuring awards are consistent and defensible against the defined criteria. Delivering these meaningful, named recognitions at scale strengthens volunteer retention, a key performance metric for peer mentoring organisations. The service provides a foundation for seasonal and annual recognition campaigns that drive ongoing platform engagement.
This is a medium-complexity backend service with a well-defined interface and a single repository dependency. It is best scheduled after the core badge system is stable, as tier eligibility logic may share criteria patterns with badge evaluation. Award period management — handling annual and seasonal windows — requires clear requirement alignment with stakeholders before implementation begins, as edge cases around boundary dates are a common source of scope creep. Testing must cover eligibility evaluation accuracy, tier assignment and revocation flows, and correct filtering of active tiers per user.
No mobile execution context reduces deployment surface area.
This service encapsulates all tier lifecycle logic — eligibility checks, assignment, revocation, and period management — backed by recognition-tier-repository. evaluateTierEligibility is the most complex method: it must query relevant metrics (potentially via peer-mentor-stats-aggregator) and compare against configured tier thresholds. assignTier should be idempotent or guard against duplicate assignments. getActiveTierForUser returns a nullable result, so callers must handle the absent-tier case gracefully.
Tier data is consumed by both profile views and coordinator dashboards, so response shape should be stable and well-typed. Backend-only execution simplifies deployment but requires async patterns for Supabase queries.
Responsibilities
- Evaluate recognition tier eligibility for users
- Assign and revoke tiers based on configured criteria
- Manage award periods (annual, seasonal)
- Expose tier data to profile and coordinator views
Interfaces
getActiveTierForUser(String userId) -> RecognitionTier?
assignTier(String tierId, String userId, DateTime awardedAt)
revokeTier(String tierId, String userId)
getAvailableTiers(String organisationId) -> List<RecognitionTier>
evaluateTierEligibility(String userId, String tierId) -> bool