Pause Management Service
Component Detail
Description
Core business logic service handling all peer mentor status transitions. Enforces valid state machine transitions (active→paused, paused→active, any→expired_cert via scheduler), persists status changes to Supabase, and triggers downstream coordinator notifications.
pause-management-service
Summaries
The Peer Mentor Pause Management Service enforces a critical compliance and safety mechanism: automatically suspending peer mentors whose certifications have lapsed. This protects the organization from liability by ensuring that uncertified individuals cannot continue in active mentoring roles without intervention. The service also supports manual pause and reactivation workflows, giving coordinators clear visibility and control over roster status. By centralizing this logic in a shared service, the business ensures consistent enforcement of pause policies regardless of which feature triggers the transition — eliminating gaps that could arise from duplicated, inconsistently implemented logic across the application.
This shared backend service has medium complexity and sits at the intersection of certification management and mentor roster management, making it a dependency for both features. It should be built before features that trigger auto-pause (e.g., certification expiry workflows) and before any UI that displays or acts on pause status. Key delivery considerations include defining the business rules for pause eligibility — edge cases such as mentors with active sessions or pending reimbursements at pause time must be specified in advance. Coordinator notification on status transitions adds an integration touchpoint with the notification service.
Testing should cover the full state machine: active → paused → reactivated, including unauthorized reactivation attempts and concurrent status changes.
The Pause Management Service is a shared backend service operating on the `peer_mentor` data model. Its interface provides `pauseMentor(mentorId, reason, initiatedBy)` and `reactivateMentor(mentorId, initiatedBy)` for state transitions, plus `getMentorPauseStatus(mentorId)` and `getPausedMentors(coordinatorId)` for read access. Internally it must enforce business rules on pause eligibility (e.g., blocking pause if preconditions fail), update the peer_mentor record's status field atomically, emit coordinator notifications on transition, and write an audit trail. The `initiatedBy` parameter supports both automated triggers (e.g., certification expiry job) and manual coordinator actions, enabling auditability.
Shared across the certification feature and the dedicated pause-management feature — changes to the state machine must be regression-tested against both consumers.
Responsibilities
- Validate and execute status transitions per allowed state machine
- Persist pause record with start_date and optional expected_return_date
- Trigger coordinator notification on status change
- Enforce role-based authorization before any transition
Interfaces
activatePause(mentorId, expectedReturnDate?)
liftPause(mentorId)
autoExpireForCertification(mentorId)
getCurrentStatus(mentorId)
getPauseHistory(mentorId)
isTransitionAllowed(currentStatus, targetStatus)
Relationships
Dependencies (2)
Components this component depends on
Dependents (1)
Components that depend on this component
Related Data Entities (2)
Data entities managed by this component