Peer Mentor Status - Entity | Meander Platform - Likepersonsapp

Description

Tracks the operational status of each peer mentor — active, paused, or auto-paused — including the reason, initiating actor, timestamps, and coordinator notification state. Supports the Pause Function (self-initiated), Resume Function, and Certification Expiry Auto-Pause features. One record per user per organization; status drives map visibility, assignment matching eligibility, and notification routing.

Data Structure

Name	Type	Description	Constraints
`id`	`uuid`	Primary key	PKrequiredunique
`user_id`	`uuid`	FK to users — the peer mentor whose status this record describes	required
`organization_id`	`uuid`	FK to organizations — scopes the status to a specific org (a user may be a peer mentor in multiple orgs)	required
`status`	`enum`	Current operational status of the peer mentor within this organization	required
`paused_at`	`datetime`	Timestamp when the peer mentor was paused (self-initiated or coordinator-initiated). NULL when status is active.	-
`paused_by`	`enum`	Actor that initiated the pause. NULL when status is active.	-
`paused_by_user_id`	`uuid`	FK to users — the coordinator or admin who initiated the pause when paused_by is 'coordinator'. NULL for self-pause and system auto-pause.	-
`pause_reason`	`text`	Optional free-text reason provided by the peer mentor or coordinator when pausing	-
`auto_pause_reason`	`enum`	Machine-readable reason for system-initiated auto-pause. NULL for manual pauses.	-
`certification_expiry_snapshot`	`datetime`	Cached copy of the certification expiry date at the time of auto-pause. Allows audit without re-querying certifications table.	-
`scheduled_resume_at`	`datetime`	Optional future datetime when the peer mentor expects to resume. Displayed in the resume flow; does not trigger automatic resume — coordinator approval may still be required.	-
`resumed_at`	`datetime`	Timestamp when the peer mentor last transitioned from paused/auto_paused back to active. NULL if never resumed.	-
`resumed_by`	`enum`	Actor that initiated the resume. NULL when not yet resumed.	-
`coordinator_notified_at`	`datetime`	Timestamp when the coordinator notification was sent for this pause/resume event. NULL if notification not yet dispatched.	-
`is_visible_on_map`	`boolean`	Derived policy flag: true only when status is 'active'. Cached here to avoid join in map queries. Updated atomically with status changes.	required
`is_eligible_for_assignments`	`boolean`	Whether this peer mentor may receive new encrypted assignment dispatches. False when paused or auto_paused.	required
`created_at`	`datetime`	Record creation timestamp (set when peer mentor is first onboarded into the org)	required
`updated_at`	`datetime`	Last modification timestamp — updated on every status transition	required

Database Indexes

idx_peer_mentor_statuses_user_org

btree unique

Columns: user_id, organization_id

idx_peer_mentor_statuses_status_org

btree

Columns: organization_id, status

idx_peer_mentor_statuses_map_eligible

btree

Columns: organization_id, is_visible_on_map

idx_peer_mentor_statuses_auto_paused

btree

Columns: status, auto_pause_reason

Validation Rules

status_enum_valid error

Validation failed

paused_at_required_when_paused error

Validation failed

paused_by_required_when_paused error

Validation failed

auto_pause_reason_required_for_system_pause error

Validation failed

scheduled_resume_at_future_only error

Validation failed

pause_reason_max_length error

Validation failed

Business Rules

single_status_per_user_per_org

on_create

Each peer mentor may have exactly one status record per organization. Enforced by the unique index on (user_id, organization_id). Status transitions mutate the existing record rather than inserting new rows.

Enforced by: Mentor Status Service

coordinator_notification_on_pause

on_update

Whenever a peer mentor's status transitions to 'paused' or 'auto_paused', the mentor-status-service must dispatch a notification to the relevant coordinator and record coordinator_notified_at. Failure to notify is logged but does not roll back the status change.

Enforced by: Mentor Status Service Notification Channel Service

map_and_assignment_flags_synced_with_status

on_update

is_visible_on_map and is_eligible_for_assignments must be updated atomically with every status change. Active → true; paused/auto_paused/inactive → false. No partial updates allowed.

Enforced by: Mentor Status Service

auto_pause_on_certification_expiry

on_update

When expiry-check-service detects that a peer mentor's certification has expired, it sets status to 'auto_paused', paused_by to 'system', auto_pause_reason to 'certification_expired', and snapshots the expiry date into certification_expiry_snapshot. The peer mentor is hidden from map and ineligible for new assignments until a valid certification is recorded and a coordinator manually resumes them.

Enforced by: Expiry Check Service Mentor Status Service

resume_requires_active_certification_if_auto_paused

on_update

A peer mentor whose status is 'auto_paused' with auto_pause_reason 'certification_expired' may only be resumed after the certifications table shows a valid non-expired certification. mentor-status-service validates this before accepting a resume request.

Enforced by: Mentor Status Service Expiry Check Service

pause_sets_paused_at_timestamp

on_update

Transitioning to any paused state must always record the paused_at timestamp. A paused record without paused_at is considered corrupt.

Enforced by: Mentor Status Service