Mentor Status Service
Component Detail
Description
Core business logic service managing peer mentor status transitions. Enforces valid state machine transitions (active → paused → active, active → inactive), triggers coordinator notifications on status change, and coordinates with the certification expiry system for HLF-specific auto-pause flows.
mentor-status-service
Summaries
The Mentor Status Service is the authoritative engine that governs whether a peer mentor is available for assignment. It enforces the rules that protect program integrity: ensuring mentors can only move between valid states, immediately notifying coordinators of any change, and automatically pausing mentors whose certifications have lapsed — a critical compliance safeguard for HLF-specific program requirements. By centralizing this logic, the organization eliminates the risk of inconsistent status handling across different parts of the application, reducing compliance exposure and ensuring that assignment pools are always accurate. This directly protects program participants and reduces coordinator overhead from manual status auditing.
A medium-complexity service spanning both mobile and backend execution contexts, making it one of the higher-effort components in this feature. It depends on the Mentor Status Repository for persistence and the Coordinator Notification Service for alerts — both must be available before end-to-end integration testing can begin. The state machine logic (active → paused → active, active → inactive) requires thorough test coverage including invalid transition rejection, concurrent update handling, and the certification expiry auto-pause path. Budget time for integration testing across contexts.
The HLF-specific certification expiry flow adds scope; confirm requirements are fully defined before implementation begins to avoid rework.
Implements a strict state machine over `MentorStatus` with transitions validated before any persistence or side effects occur. Key methods: `pauseMentor(mentorId, reason?)`, `reactivateMentor(mentorId)`, `getMentorStatus(mentorId)`, `isEligibleForAssignment(mentorId)`, and `pauseOnCertificationExpiry(mentorId)`. Depends on `mentor-status-repository` for reads/writes and `coordinator-notification-service` for post-transition alerts — notification must fire after successful persistence, not before, to avoid phantom alerts on failed transitions. The service runs in both mobile (offline-capable) and backend contexts; ensure the mobile implementation handles offline queuing gracefully.
Use the repository pattern to keep persistence details abstracted, enabling easy test doubles. Certification expiry auto-pause must be idempotent — safe to call multiple times without double-notifying coordinators.
Responsibilities
- Execute pause and reactivation status transitions with validation
- Trigger coordinator notification on any status change
- Expose status query methods used by assignment pool filtering
Interfaces
pauseMentor(mentorId: String, reason: String?): Future<void>
reactivateMentor(mentorId: String): Future<void>
getMentorStatus(mentorId: String): Future<MentorStatus>
isEligibleForAssignment(mentorId: String): Future<bool>
pauseOnCertificationExpiry(mentorId: String): Future<void>
Relationships
Dependencies (2)
Components this component depends on