Course Enrollment
Data Entity
Description
A join record linking a user to a course with enrollment status (registered, waitlisted, attended, withdrawn). Used for capacity enforcement, coordinator oversight of participation, and automatic certification generation upon attendance confirmation.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Globally unique identifier for the enrollment record | PKrequiredunique |
course_id |
uuid |
Foreign key reference to the course being enrolled in | required |
user_id |
uuid |
Foreign key reference to the user (peer mentor) enrolling in the course | required |
status |
enum |
Current enrollment lifecycle state. 'registered' = confirmed seat; 'waitlisted' = capacity reached, queued; 'attended' = coordinator confirmed presence; 'withdrawn' = user or coordinator cancelled | required |
enrolled_at |
datetime |
Timestamp when the enrollment record was first created (UTC). Immutable after creation. | required |
attended_at |
datetime |
Timestamp when attendance was confirmed by a coordinator. Null until status transitions to 'attended'. Triggers certification generation pipeline. | - |
withdrawn_at |
datetime |
Timestamp when the enrollment was withdrawn by the user or a coordinator. Null until status transitions to 'withdrawn'. | - |
waitlist_position |
integer |
Ordinal position in the waitlist queue when status is 'waitlisted'. Used to promote waitlisted users when a registered seat opens. Null for non-waitlisted records. | - |
enrolled_by |
uuid |
User ID of the coordinator who performed a proxy enrollment on behalf of the peer mentor. Null when the user enrolled themselves. Used for audit and oversight. | - |
attendance_confirmed_by |
uuid |
User ID of the coordinator who confirmed attendance and set status to 'attended'. Required when attended_at is set. Used for certification audit trail. | - |
certification_generated |
boolean |
Whether the certification generation pipeline has been triggered for this enrollment. Prevents duplicate certificate issuance on retry scenarios. Set to true after successful certification creation. | required |
withdrawal_reason |
text |
Optional free-text reason provided when enrollment is withdrawn. Captured for coordinator record-keeping and reporting. Null for non-withdrawn records. | - |
notes |
text |
Internal coordinator notes about this enrollment, e.g. accommodation needs, special circumstances. Not visible to the enrolled user. | - |
created_at |
datetime |
Record creation timestamp (UTC). Identical to enrolled_at at creation; preserved separately to support audit queries. | required |
updated_at |
datetime |
Last modification timestamp (UTC). Updated on every status transition and field change. | required |
Database Indexes
idx_course_enrollment_user_course_unique
Columns: user_id, course_id
idx_course_enrollment_course_id
Columns: course_id
idx_course_enrollment_user_id
Columns: user_id
idx_course_enrollment_status
Columns: status
idx_course_enrollment_course_status
Columns: course_id, status
idx_course_enrollment_waitlist
Columns: course_id, waitlist_position
idx_course_enrollment_certification_pending
Columns: certification_generated, status
Validation Rules
status_enum_constraint
error
Validation failed
attended_at_consistency
error
Validation failed
withdrawn_at_consistency
error
Validation failed
waitlist_position_consistency
error
Validation failed
course_id_exists
error
Validation failed
user_id_exists
error
Validation failed
enrolled_by_role_check
error
Validation failed
attended_at_not_before_enrolled_at
error
Validation failed
legal_status_transition
error
Validation failed
organization_scope_check
error
Validation failed
Business Rules
capacity_enforcement
When a user attempts to enroll in a course that has reached its maximum participant capacity, the enrollment must be created with status 'waitlisted' and assigned the next sequential waitlist_position. Direct enrollment with status 'registered' is only permitted when current registered count is below the course capacity limit.
no_duplicate_active_enrollment
A user may only hold one enrollment record per course at a time. Attempting to create a second enrollment for the same (user_id, course_id) pair is rejected with a conflict error. The unique index on (user_id, course_id) enforces this at the database level.
auto_certification_on_attendance
When a coordinator confirms attendance and transitions an enrollment's status to 'attended', the system must automatically invoke the CertificationService to issue or renew the peer mentor's certification linked to this course. This trigger fires only if certification_generated is false. On successful certificate creation, certification_generated is set to true atomically within the same transaction.
waitlist_promotion_on_withdrawal
When a 'registered' enrollment transitions to 'withdrawn', the system must check for waitlisted enrollments for the same course ordered by waitlist_position ascending. The first waitlisted enrollment must be promoted to 'registered' status, its waitlist_position cleared, and a push notification sent to the newly registered user.
attendance_requires_coordinator_actor
The status transition to 'attended' may only be performed by a user holding the Coordinator or Organization Administrator role for the local association that owns the course. Peer mentors cannot self-confirm attendance. The attendance_confirmed_by field must be populated with the acting coordinator's user ID.
proxy_enrollment_audit_trail
When a coordinator enrolls a peer mentor on their behalf, the enrolled_by field must be set to the coordinator's user ID. This is mandatory for proxy enrollments and must be null for self-enrollments. Used for Bufdir compliance audit and coordinator oversight reporting.
withdrawn_enrollment_immutable
Once an enrollment reaches 'withdrawn' status, no further status transitions are permitted. Re-enrollment requires creating a new enrollment record. This preserves the historical record of the original enrollment and withdrawal for audit purposes.
certification_generation_idempotency
The certification_generated flag prevents duplicate certificate issuance if the attendance confirmation event is processed more than once (e.g. due to retry logic or network errors). CertificationService must check this flag before issuing and set it atomically on success.