Certification
Data Entity
Description
Records a peer mentor's earned certification, linking them to the course they completed. Tracks issuance date, expiry date, and current status. Drives the Certification Expiry Auto-Pause feature (expired cert triggers automatic peer mentor deactivation) and powers the Digital Peer Mentor Certificate display in the mobile app.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key | PKrequiredunique |
user_id |
uuid |
FK to users — the peer mentor who holds this certification | required |
course_id |
uuid |
FK to courses — the course this certification was awarded for. Nullable for legacy or manually issued certs not tied to a course record. | - |
organization_id |
uuid |
FK to organizations — the tenant that issued the certification. Enables org-scoped visibility and admin queries. | required |
certificate_number |
string |
Human-readable certificate identifier, e.g. 'HLF-2025-0042'. Unique within an organization. Used on the printable/digital certificate display and for external verification. | required |
certificate_type |
enum |
Category of certification. 'peer_mentor' is the standard credential. 'refresher' is a renewal/recertification. 'advanced' is a higher-tier credential. | required |
status |
enum |
Lifecycle state of the certification. 'active' — valid and in effect. 'expired' — past expires_at with no renewal. 'suspended' — temporarily deactivated (e.g. by admin during investigation). 'revoked' — permanently invalidated. | required |
issued_at |
datetime |
Timestamp when the certification was formally awarded. Used as the certificate issue date on the digital display. | required |
expires_at |
datetime |
Timestamp when the certification expires. Nullable for certifications with no expiry (some orgs issue lifetime certs). When set, the expiry-check-service monitors this field daily and triggers auto-pause when crossed. | - |
issued_by |
string |
Name of the person or body that issued the certification, e.g. 'Hørselsforbundet' or a coordinator's full name. Displayed on the digital certificate. | - |
digital_token |
string |
Cryptographic verification token (HMAC or similar) embedded in the certificate QR code or deep link, allowing offline verification of authenticity without querying the database. | unique |
auto_paused |
boolean |
True if this certification's expiry triggered an automatic peer mentor status pause. Set by expiry-check-service. Allows the system to distinguish auto-pause (certification-driven) from manual pause (user-initiated). | required |
renewal_reminder_sent_at |
datetime |
Timestamp when the last renewal reminder notification was dispatched. Prevents duplicate reminder sends when the scheduled job runs repeatedly near expiry. | - |
notes |
text |
Admin-facing freetext notes — e.g. reason for revocation, manual override justification, or context for a legacy certificate import. | - |
created_at |
datetime |
Record creation timestamp | required |
updated_at |
datetime |
Last modification timestamp | required |
Database Indexes
idx_certifications_user_id
Columns: user_id
idx_certifications_org_id
Columns: organization_id
idx_certifications_user_course
Columns: user_id, course_id, certificate_type
idx_certifications_org_number
Columns: organization_id, certificate_number
idx_certifications_expires_at_status
Columns: expires_at, status
idx_certifications_digital_token
Columns: digital_token
Validation Rules
expires_at_after_issued_at
error
Validation failed
certificate_number_format
error
Validation failed
status_transition_valid
error
Validation failed
course_id_org_match
error
Validation failed
user_id_org_match
error
Validation failed
Business Rules
expiry_triggers_auto_pause
When expires_at is in the past and status is 'active', the expiry-check-service transitions status to 'expired' and instructs mentor-status-service to auto-pause the peer mentor. Sets auto_paused = true on the certification record. HLF requirement: expired cert removes the mentor from the local chapter website automatically.
single_active_cert_per_user_per_type
A user may have at most one 'active' certification per certificate_type. Issuing a new cert of the same type automatically expires the previous one, ensuring the digital certificate display always shows the current credential.
revoked_cert_permanent
A certification with status 'revoked' cannot be transitioned back to 'active' or 'suspended'. Revocation is permanent. A new certification record must be created if the user is to be recertified.
renewal_reminder_window
renewal-notification-service sends a push + email reminder when expires_at is within 30 days and renewal_reminder_sent_at is null or older than 7 days. This implements the Certificate Renewal Reminder feature requirement.
org_scoped_visibility
Certifications are only visible to users within the same organization_id. Global admins with time-bounded support access may read certifications for the granted org only.
digital_token_on_issuance
When a certification is created, certificate-service generates a cryptographic digital_token (HMAC-SHA256 of id + issued_at + organization_id using a server secret). Token is embedded in the QR code on the digital certificate and enables offline verification.