Peer Mentor Status Log
Data Entity
Description
An immutable audit trail of status transitions for a peer mentor — active, paused, suspended, deactivated. Each record captures the new status, reason, expected return date, and the actor who triggered the change. Enables coordinators to view the full status history and supports automated certification-expiry deactivation.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Unique identifier for this status log entry. Generated server-side as a UUID v4. | PKrequiredunique |
peer_mentor_id |
uuid |
Foreign key reference to the peer_mentors table. Identifies which peer mentor this status transition belongs to. | required |
status |
enum |
The new status that this log entry records the peer mentor transitioning INTO. Represents the state after the change. | required |
previous_status |
enum |
The status the peer mentor held immediately before this transition. Null only for the very first log entry when the peer mentor record is created. Stored for complete audit chain reconstruction without joins. | - |
reason |
text |
Human-readable explanation for the status change. For system-triggered transitions (certification expiry), this is a standardised machine-generated message. For manual transitions, this is free-text entered by the coordinator or peer mentor via the Pause Toggle Screen. | - |
return_date |
datetime |
Optional expected return-to-active date collected when a peer mentor is paused. Only populated when status = 'paused'. Stored in UTC. Used by the Pause Status Widget to inform coordinators of expected availability. | - |
actor_id |
uuid |
Foreign key reference to the users table identifying who or what triggered this status transition. References a real user record even for system actors — a dedicated system service account user is used for automated transitions (e.g. certification expiry job). | required |
actor_type |
enum |
Discriminator indicating whether the status change was triggered by a human user acting through the UI or by an automated system process. Enables filtering of audit history to distinguish manual coordinator decisions from automated certification-expiry events. | required |
created_at |
datetime |
UTC timestamp of when this log entry was written. Set by the database server at insert time and never modified. Serves as the authoritative event time for the status transition. | required |
Database Indexes
idx_peer_mentor_status_log_peer_mentor_id
Columns: peer_mentor_id
idx_peer_mentor_status_log_peer_mentor_created
Columns: peer_mentor_id, created_at
idx_peer_mentor_status_log_status
Columns: status
idx_peer_mentor_status_log_actor_id
Columns: actor_id
idx_peer_mentor_status_log_created_at
Columns: created_at
Validation Rules
peer_mentor_id_exists
error
Validation failed
actor_id_exists
error
Validation failed
status_enum_value
error
Validation failed
previous_status_enum_value
error
Validation failed
actor_type_enum_value
error
Validation failed
reason_max_length
error
Validation failed
created_at_not_manipulatable
error
Validation failed
Business Rules
immutable_append_only
Status log entries are immutable once written. No UPDATE or DELETE operations are permitted. All history is preserved permanently. Corrections to incorrect entries must be handled by writing a corrective new entry, not modifying existing ones.
valid_status_transition
Only legal status transitions are permitted: active → paused, active → suspended, active → deactivated, paused → active, paused → suspended, paused → deactivated, suspended → active, suspended → deactivated. A deactivated peer mentor cannot transition to any status other than active (reactivation). The transition active → active is rejected (no-op transitions not logged).
return_date_only_for_paused_status
The return_date field must be null for all status values except 'paused'. If a non-null return_date is provided when status is not 'paused', the write is rejected with a validation error.
return_date_must_be_future
When provided, return_date must be a future date at the time of writing. A return_date in the past is rejected to prevent meaningless historical return dates being stored.
system_actor_for_automated_transitions
When a status transition is triggered by the Certification Expiry Background Job, the actor_type must be 'system' and actor_id must reference the designated system service account. This ensures audit history clearly identifies automated vs. human-initiated transitions.
no_duplicate_consecutive_status
A new log entry must not be created if the new status is identical to the peer mentor's current status (i.e. the status field of the most recent log entry for this peer_mentor_id). Prevents redundant audit entries from automated jobs re-processing already-deactivated mentors.
coordinator_scope_enforcement
Only users with Coordinator, Organization Administrator, or Global Administrator roles may trigger status transitions for a peer mentor. The peer mentor's own role is permitted to trigger the paused → active transition (self-resume). The actor's organization scope must include the peer mentor's local association.
post_transition_notification
After every successful status log entry is written, the Pause Notification Service must be invoked to dispatch push notifications to the relevant coordinator(s). The notification must reference the new status, reason, and return_date. This rule applies to both manual and system-triggered transitions.
CRUD Operations
Storage Configuration
Entity Relationships
A peer mentor has a full history of status transitions (active, paused, suspended, deactivated)