Certification
Data Entity
Description
Records a peer mentor's certification status for a specific course or training program, including issue date, expiry date, and current validity. Drives auto-pause logic when a certification lapses and enables digital certificate display in-app.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key | PKrequiredunique |
user_id |
uuid |
Foreign key to users table — the peer mentor who holds this certification | required |
course_id |
uuid |
Foreign key to courses table — the course this certification was awarded for. Nullable for manually issued certifications not tied to a course. | - |
organization_id |
uuid |
Foreign key to organizations — the issuing organization. Scopes certification to the correct tenant. | required |
certificate_type |
enum |
Category of certification. 'peer_mentor' is the primary type (the formal Peer Mentor Certificate); 'course_completion' for individual course completions; 'specialist' for advanced designations. | required |
status |
enum |
Current validity state of the certification. 'active' means valid; 'expired' means past expiry_date; 'revoked' means manually invalidated by admin; 'pending' means issued but awaiting confirmation. | required |
certificate_number |
string |
Human-readable certificate identifier shown on the digital certificate screen. Organization-scoped unique. | - |
issued_at |
datetime |
Date and time the certification was issued or awarded | required |
expiry_date |
datetime |
Date the certification expires. Null means the certification does not expire. When this date passes, the certification transitions to 'expired' and the auto-pause trigger fires. | - |
renewal_reminder_sent_at |
datetime |
Timestamp of the last renewal reminder notification dispatched. Used by RenewalReminderService to avoid duplicate reminders. | - |
auto_paused_at |
datetime |
Timestamp when the auto-pause was triggered due to this certification expiring. Null if auto-pause has not occurred. | - |
revoked_at |
datetime |
Timestamp when the certification was manually revoked by an admin | - |
revoked_by_user_id |
uuid |
User ID of the admin who revoked the certification | - |
revocation_reason |
text |
Free-text reason provided by the admin when revoking | - |
metadata |
json |
Extensible bag for org-specific certificate data (e.g. physical card number, external certificate ID from a training provider, custom fields) | - |
created_at |
datetime |
Record creation timestamp | required |
updated_at |
datetime |
Record last-updated timestamp | required |
Database Indexes
idx_certifications_user_id
Columns: user_id
idx_certifications_organization_id
Columns: organization_id
idx_certifications_course_id
Columns: course_id
idx_certifications_user_org_type
Columns: user_id, organization_id, certificate_type
idx_certifications_status_expiry
Columns: status, expiry_date
idx_certifications_expiry_date
Columns: expiry_date
Validation Rules
expiry_after_issued
error
Validation failed
user_belongs_to_organization
error
Validation failed
course_belongs_to_organization
error
Validation failed
status_transition_guard
error
Validation failed
certificate_number_format
warning
Validation failed
Business Rules
expiry_triggers_auto_pause
When a peer_mentor certificate transitions to 'expired' (expiry_date <= now and status = active), CertificationExpiryMonitor fires AutoPauseTriggerService to pause the peer mentor's status. The auto_paused_at timestamp is recorded on the certification record and the peer_mentor_status_history is updated.
renewal_reminder_schedule
RenewalReminderService dispatches a renewal reminder notification 30 days before expiry_date (and again at 7 days). It sets renewal_reminder_sent_at to prevent duplicate sends within the same reminder window.
active_certification_required_for_assignment_eligibility
A peer mentor must have at least one active peer_mentor certificate to be eligible for encrypted assignment dispatch. EligibilityFilterService checks certification status before including a mentor in assignment targeting.
single_active_peer_mentor_cert_per_org
A user may hold at most one active peer_mentor certificate per organization at a time. Issuing a new one must either revoke or expire the previous one.
revocation_requires_reason
Changing status to 'revoked' requires a non-empty revocation_reason and records revoked_at and revoked_by_user_id for audit trail.
physical_card_parallel_existence
For HLF, the digital certificate does not replace the physical card — both coexist. The metadata field may carry a physical_card_number. No business logic enforces the physical card, but the digital certificate must not imply the physical card is invalid.