Enrollment

Feature Owner (original Hand-Off): Joshua Uriel Tribiana
Updated by / current owner: Patrick Babala (patpatty19)
Module: User Mgmt & Enrollment
Priority: P1
Status: Handoff — Updated and Published (v2.0)
Date: 2026-10-01
Issue: [6.2] Enrollment — issue number not confirmable without GitHub access (not fabricated).
PRs covered by this revision: #706 (add-learners enhancement), #718 (bulk-enrollment fixes), #790 (enrollment/file-upload + progress fixes), #869 (default cohorts on enrollment), #871 (H3 bulk-CSV caps + recovery link), #875 (enrollment-count triggers + quest_enrollments RLS hardening). Security ticket: #860.
Companion doc: Internal Technical Guide — Internal-Technical-Guide-Enrollment.md (architecture, DB schema, API specs, helpers, ops, troubleshooting). This Hand-Off stays product-facing; where engineering depth is needed it cross-references the ITG instead of duplicating it.


EXECUTIVE SUMMARY

What is this feature?

Enrollment is the access-control and onboarding layer that connects learners to quests. It lets creators invite or assign learners to a quest (individually or by CSV), track their status and progress, and manage participation, while authenticated learners can self-enroll into published quests.

Why does it matter?

Enrollment is the system boundary between “content exists” and “a learner can actually access and progress through it.” Without a reliable enrollment model, quests cannot be assigned, tracked, or completed in a structured way.

What’s the MVP scope?

The current implementation includes:

  • Creator-side learner management for a quest

  • Manual add (by email) and bulk CSV import of learners

  • Automatic learner account provisioning / recovery when the email is new

  • Learner self-enrollment into published quests

  • Enrollment progress and status tracking

  • Enrollment deletion and status updates

  • Enrollment-time provisioning into the creator’s default cohort

Shipped scope added in v2.0:

  • Auto-provisioning + account recovery (PRs #706 / #718 / #871): enrolling a new email creates the learner account and sends an account + set-password email; a partially-provisioned account is recovered instead of erroring.

  • Bulk CSV hardening (PR #871): uploads are capped at 1 MB / 500 rows; an existing user’s password is never reset — a one-time recovery link is issued instead; per-row failures are reported.

  • Per-row CSV error reporting (PR #718): bulk-create returns failedEnrollments[] with reasons (Already enrolled, User is not a learner, Failed to provision account, Account exists but setup incomplete) alongside successfulEnrollments.

  • Enrollment limits (PR #718): enrollment_limit is enforced before an enrollment is created.

  • Trigger-maintained enrollment count (PR #875 / #860): quests.enrollment_count is now kept correct by database triggers on every write path.

  • Default cohorts (PR #869): each newly enrolled learner is provisioned into the creator’s default cohort (Feature [11.5], product-side).

  • Learner self-enrollment (authenticated, published quests only; idempotent).

Still deferred: public/anonymous enrollment links, paid/seat-based gating, and analytics dashboards for cohort activity.


1. USER PAIN POINT & SOLUTION

Current State (Without Feature)

A quest may be published and complete, but there is no structured way for creators to assign or manage participation or for learners to enter the experience in a tracked, persistent way.

Pain Point

  • Emotional: Frustration when learners cannot access or be tracked in a quest experience.

  • Functional: No reliable access-control or progression mechanism for assigned quest participation.

  • Business Impact: Weak adoption, poor tracking, and no clear learning journey ownership.

Future State (With Feature)

Creators can manage who is enrolled (including auto-provisioning new learner accounts), learners can self-enroll into published quests, and the system tracks each learner’s status and progress. New enrollments also slot the learner into the creator’s default cohort so the learning journey is organized from day one.

Marketing Hook

“Turn published quests into guided learning journeys with structured enrollment, progress tracking, and learner management.”


2. CODEBASE ASSESSMENT

Current Implementation Status

Enrollment is implemented through a creator management page plus learner-facing enrollment APIs and progress hooks. Enrollment creation now auto-provisions learner accounts and provisions default cohorts; the enrollment count is maintained in the database.

Primary Files

  • app/quest-editor/[questID]/(sections)/enrollment/page.tsx — creator-facing enrollment dashboard for a quest. Supports adding learners (inline dialog with email autocomplete), bulk import, filtering, progress updates, status updates, and deletion.

  • app/api/creator/enrollment/create-enrollment/route.ts — creates a single enrollment by email; verifies/auto-provisions the learner account, enforces the LEARNER role and enrollment limit, blocks duplicates, and sends the enrollment email.

  • app/api/creator/enrollment/bulk-create/route.ts — bulk CSV enrollment with size/row caps and per-row results.

  • app/api/creator/enrollment/list-enrollments/route.ts — lists all enrollments for a quest.

  • app/api/creator/enrollment/search-emails/route.ts — learner email autocomplete (agency-scoped, excludes already-enrolled learners).

  • app/api/creator/enrollment/update-enrollment/route.ts — updates enrollment status and/or progress.

  • app/api/creator/enrollment/delete-enrollment/route.ts — deletes an enrollment from a quest.

  • app/api/learner/enroll/route.ts — learner self-enrollment endpoint for published quests (idempotent).

  • app/api/learner/get-enrollment/route.ts — retrieves the current learner enrollment for a quest.

  • lib/enrollment/enrollmentService.ts — frontend service wrapper for create/list/update/delete enrollment actions.

Current Behavior Summary

  • Creators can add learners by email (the display name is derived from the email, or matched to an existing agency learner).

  • The creator enrollment page shows learner status, date enrolled, progress, and actions.

  • New emails are auto-provisioned (account + set-password/recovery email); existing learners receive a quest-link email.

  • Bulk CSV import is capped and reports per-row outcomes.

  • Learners can self-enroll into published quests.

  • Enrollment data is stored in quest_enrollments and linked to app_users; progress is a JSON payload (percentage, visited_cards, last_visited_at, completed_nodes).

  • quests.enrollment_count is maintained by database triggers; enrollment_limit is enforced before creating an enrollment.

Strengths Already Present

  • Strong creator management workflow for learners.

  • Enrollment creation is guarded by role, ownership, duplicate, and limit checks.

  • Self-enrollment is idempotent and rejects unpublished quests.

  • Progress and status are tracked per learner and quest.

  • Account provisioning and recovery are handled without exposing password resets.

Gaps / Hardening Opportunities

  • Enrollment count updates are not yet fully synchronized in some flows. Resolved (v2.0): counts are maintained by database triggers on every insert/delete (PR #875 / #860).

  • The system relies on role and ownership checks but could add enrollment limits. Resolved (v2.0): enrollment_limit is enforced (PR #718).

  • The creator UI still uses direct prompts for some custom progress editing rather than a fully structured modal. (Still open — cosmetic.)

  • Rich bulk operations (edit/remove many rows at once) remain limited to import + per-row status/progress actions. (Still open.)


3. 4D FRAMEWORK MAPPING

Diagnose

Learners need structured access to quests, and creators need a way to manage participation and track progress.

Design

Enrollment is modeled as a first-class relationship between learners, quests, and progress state, surfaced through both creator and learner experiences, with account provisioning and default-cohort placement on enrollment.

Develop

Creators can add and manage learners (including bulk CSV and auto-provisioning), while learners can access quests once enrolled and progress is tracked automatically.

Deliver

A quest becomes a structured learning experience with persistent learner state and progress visibility.


4. USER FLOWS

Entry Point

A creator opens the Enrollment tab for a quest, or a learner visits a published quest and chooses to enroll.

Success Criteria

  • The learner becomes associated with the quest.

  • The creator can see the learner in the enrollment list.

  • The learner’s progress and status are tracked.

  • The learner receives an enrollment (and, if new, an account + set-password) email.

Main Flow (Happy Path)

  • Creator opens the quest enrollment page.

  • Creator adds a learner by email or imports a CSV batch.

  • The system resolves the account — auto-provisioning or recovering it when the email is new — verifies the LEARNER role, and checks the enrollment limit.

  • The system creates the enrollment record (ongoing) and provisions the creator’s default cohort.

  • The learner receives an enrollment notification email (existing learners) or an account + set-password email (new learners).

  • The learner can access and begin the quest (existing learners) or set a password and then access it.

  • The creator can update the learner’s status and progress over time.

Edge Cases

  • Learner already enrolled: No duplicate record is created; the row is reported as already enrolled in bulk imports.

  • Learner account missing: The account is auto-provisioned (or recovered), so the creator no longer sees an error in the common case. A partially-set-up account surfaces as "Account exists but setup incomplete".

  • Wrong role: Only LEARNER accounts are accepted; otherwise "User is not a learner".

  • Enrollment limit reached: Enrollment is blocked ("Enrollment limit reached for this quest").

  • CSV too large: Files over 1 MB or 500 rows are rejected.

  • Progress update invalid: Progress is capped to 0–100.

Decision Points

  • IF the learner is already enrolled → no duplicate entry is created.

  • IF the quest is not published → self-enrollment is rejected.

  • IF the creator removes an enrollment → the learner loses access to that quest’s tracked progress relationship.

  • IF the creator has an agency → enrolling a learner also provisions the default cohort; individual (non-agency) creators do not get cohort provisioning.


5. INFORMATION ARCHITECTURE

Primary Information (Always visible)

  • Learner name and email

  • Current status (ongoing or finished)

  • Date enrolled

  • Progress percentage

Secondary Information

  • Completed task count / progress detail metadata

  • Action menu for progress and removal actions

Tertiary Information (Hidden until needed)

  • Internal JSON progress payload

  • Enrollment IDs used for management actions

Actions

  • Primary CTA: Add Learner / Bulk Import

  • Secondary Actions: Mark as finished or ongoing, Reset progress, Remove enrollment


6. WIREFRAMES

The experience is embedded in the quest editor’s enrollment section.

Key Screens:

  • Enrollment dashboard with learner table

  • Add learner dialog (with email autocomplete)

  • Bulk import modal (CSV)

  • Confirmation modal for removal

Annotations:

  • Enrollment is managed per quest.

  • Status and progress are visible in a table view.

  • Actions are grouped around learner administration.


7. WIREFLOWS

Creator opens enrollment → adds or imports learner → learner account is resolved/provisioned → learner is enrolled and (if applicable) placed in the default cohort → learner is notified → creator monitors progress → status or progress updates are applied.


8. PROTOTYPE

Figma Prototype Link: Not currently available for this feature.

How to test:

  • Open a quest in the editor and visit the Enrollment section.

  • Add a learner by email (try both a new email and an existing learner).

  • Confirm the learner appears in the table with an ongoing status.

  • Update their progress or mark them finished.

  • Remove the enrollment and verify it disappears.


9. DATA MODEL

Core Table

The feature depends on the quest_enrollments table with the following concepts:

  • quest_id

  • learner_id — the internal app_users.id UUID (not a Clerk ID)

  • status

  • progress

  • enrolled_at

Progress Shape

Progress is a JSON object with fields such as percentage, visited_cards, last_visited_at, and completed_nodes.

Relationship to Users

Enrollment records link to app_users for the learner identity and email display. quests.enrollment_count is maintained by database triggers and compared against quests.enrollment_limit.

Full column types and the trigger definitions are in ITG §4 (Data Model / Schema).


10. API CONTRACTS

Creator — Create Enrollment

  • Endpoint: POST /api/creator/enrollment/create-enrollment

  • Request: { "quest_id": "uuid", "learner_email": "learner@example.com" }

  • Behavior: Validates quest ownership; auto-provisions or recovers the learner account; verifies the LEARNER role; prevents duplicate enrollments; enforces the enrollment limit; inserts a quest_enrollments record; sends an enrollment (or account + set-password) email.

Creator — Bulk Create

  • Endpoint: POST /api/creator/enrollment/bulk-create?questId={questId} (multipart CSV with an email column)

  • Behavior: Enforces the 1 MB / 500-row caps; provisions/recover accounts; returns { successfulEnrollments, failedEnrollments: [{ email, reason }] }; never resets an existing user’s password (recovery link instead).

Creator — List Enrollments

  • Endpoint: GET /api/creator/enrollment/list-enrollments?quest_id={questId}

  • Behavior: Returns enrollments and related learner data for the specified quest.

Creator — Search Emails

  • Endpoint: GET /api/creator/enrollment/search-emails?q={query}&quest_id={questId}

  • Behavior: Agency-scoped autocomplete; returns up to 20 not-yet-enrolled learner emails.

Creator — Update Enrollment

  • Endpoint: PUT /api/creator/enrollment/update-enrollment

  • Request: { "enrollment_id": "uuid", "quest_id": "uuid", "status": "finished", "progress": 75 }

  • Behavior: Updates status and/or progress; caps progress to 0–100.

Creator — Delete Enrollment

  • Endpoint: DELETE /api/creator/enrollment/delete-enrollment

  • Request: { "enrollment_id": "uuid", "quest_id": "uuid" }

  • Behavior: Removes the enrollment from the quest.

Learner — Self-Enrollment

  • Endpoint: POST /api/learner/enroll

  • Request: { "quest_id": "uuid" }

  • Behavior: Requires a published quest; idempotent; creates an enrollment record for the authenticated learner and provisions the default cohort.

Learner — Get Enrollment

  • Endpoint: GET /api/learner/get-enrollment

  • Behavior: Retrieves the current learner’s enrollment for a quest.

Auth checks, exact error messages, and request/response shapes are in ITG §4 (API Specification).


11. DATA REQUIREMENTS

Frontend Needs

The creator page needs:

  • The list of enrollments for a quest.

  • The ability to add, update, and delete them.

  • Visibility into progress and status.

  • The learner email autocomplete (search-emails).

Learner Needs

The learner self-enrollment flow needs:

  • Access to a published quest ID.

  • A valid authenticated learner account.

  • A safe, idempotent enrollment path.


12. SECURITY & AUTHORIZATION

Who can access this feature?

  • Creator: ✔

  • Learner: ✔

  • Reviewer: ✘

Authorization Logic

  • Creator routes verify that the quest is owned by the authenticated creator (or belongs to the creator’s agency) via getCreatorAuthContext() / verifyAgencyResourceOwnership().

  • Learner self-enrollment requires an authenticated learner account and a published quest.

  • Only existing (or newly auto-provisioned) LEARNER accounts can be assigned to a quest.

  • quest_enrollments is protected by Row Level Security; enrollment counts are trigger-maintained.

Updated in v2.0: authentication is Supabase Auth (not Clerk). The legacy-named app_users.clerk_id column now stores the Supabase auth UUID. See ITG §3 and §4.


13. ERROR HANDLING

Common Errors

  • Missing quest or learner email.

  • Learner already enrolled ("Learner is already enrolled in this quest").

  • Non-learner account ("Only users with LEARNER role can be enrolled in quests.").

  • Enrollment limit reached ("Enrollment limit reached for this quest").

  • Quest not published for self-enrollment.

  • CSV over the size/row cap, or malformed.

  • Invalid progress value.

Handling Guidance

  • Return clear status and message payloads to the UI.

  • Surface bulk per-row failures from failedEnrollments[] rather than failing the whole import.

  • Keep the UI responsive by updating local state after successful mutations when possible.

  • Prefer the automatic account-recovery path over showing a hard error when an email exists but is only partially provisioned.


14. TESTING CHECKLIST

Happy Path

  • A creator can add a learner to a quest (existing learner).

  • A creator can add a brand-new email, which is auto-provisioned and emailed a set-password link.

  • The learner appears in the enrollment table.

  • The creator can update progress and status.

  • The learner can self-enroll into a published quest.

  • A valid CSV imports and reports successful/failed rows.

Edge Cases

  • Duplicate enrollment is prevented (single and bulk).

  • Non-LEARNER accounts cannot be enrolled.

  • Missing or invalid inputs return proper errors.

  • Progress is capped correctly between 0 and 100.

  • Enrollment limit blocks the enrollment when reached.

  • CSV over 1 MB or 500 rows is rejected.

  • Unpublished quest rejects self-enrollment.

  • Self-enrollment is idempotent (no duplicate record).

  • Recovery/set-password link resolves for an auto-provisioned learner.


15. OPEN QUESTIONS

For Product

  • Should paid/seat-based gating be added to the flow? — Still open.

  • Should creator-invited learners receive a richer onboarding experience after enrollment? — Still open.

For Engineering

  • Should the creator enrollment page support richer bulk operations (multi-row edit/remove)? — Still open.

  • Should enrollment counts be updated more systematically across the app? — Resolved (v2.0): counts are maintained by database triggers on every write path (PR #875 / #860).

  • Should enrollment limits be enforced? — Resolved (v2.0): enrollment_limit is enforced before creating an enrollment (PR #718).


16. OUT OF SCOPE (v1.1+)

  • Advanced cohort-based enrollment rules — Resolved (v2.0): group-based enrollment shipped as Feature [11.5], and enrollment now provisions the creator’s default cohort (PR #869). Detailed cohort management is documented under [11.5].

  • Automated seat management or paid enrollment gating — still out of scope.

  • Public/anonymous enrollment links — still out of scope (self-enrollment requires authentication).

  • Full analytics dashboards for cohort activity — still out of scope.


17. SUCCESS METRICS

  • Learners are successfully added to quests and start their learning journey.

  • Creators can manage participation without manual workarounds.

  • Progress and completion state are visible and reliable.

  • Bulk import success rate (with clear per-row failure reasons).

  • Auto-provisioning success rate and set-password link delivery.


18. DEPENDENCIES

This feature depends on

  • The quest_enrollments data model.

  • The creator authentication layer (Supabase Auth — corrected in v2.0; was “Clerk”).

  • The learner authentication layer (Supabase Auth).

  • The quest publishing state.

  • The default-cohort service (Feature [11.5], PR #869).

  • The email service (enrollment + account provisioning emails).

These features depend on this

  • Quest progression and completion tracking.

  • Learner dashboards and quest access flows.

  • Leaderboards and achievement/notification flows (progress is the trigger).


19. TIMELINE & OWNERSHIP

Implementation Ownership

  • Original owner / Hand-Off author: Joshua Uriel Tribiana

  • Implementation updates & current owner: Patrick Babala (author/co-author of PRs #706, #718, #790, #869, #871, #875)

  • QA: Joylynne Esportuno (teruterubozuuu) — original

  • Shipped: core Enrollment (2026-06); v2.0 updates merged 2026 (PRs #706, #718, #790, #869, #871, #875)

  • Estimated Completion: core complete; remaining items are the Open Questions and Out of Scope sections above


REFERENCES

  • Issue: [6.2] Enrollment — number not confirmable without GitHub access.

  • Security ticket: #860 — Security audit L5 (enrollment-count trigger + RLS hardening), delivered by PR #875.

  • v2.0 PRs: #706 — add-learners enhancement; #718 — bulk-enrollment fixes (random temporary passwords, enrollment_limit, count syncing, progress dialog); #790 — file-upload / enrollment-progress fixes; #869 — default cohorts on enrollment; #871 — H3 bulk-CSV caps + recovery link instead of password reset; #875 — enrollment-count triggers + quest_enrollments RLS hardening.

  • Companion ITG: Internal-Technical-Guide-Enrollment.md.

  • Offline limitation: the [6.2] issue number and sub-issue numbers could not be resolved without GitHub access.


VERSION HISTORY

  • 2.0 — 2026-10-01 — Patrick Babala. Hand-Off overhaul. Updated the original outline in place: auto-provisioning and account recovery; bulk CSV caps and per-row error reporting; enrollment limits; trigger-maintained enrollment count; default-cohort provisioning on enrollment; Clerk → Supabase Auth; learner_id clarified as the app_users.id UUID; API contracts corrected (list-enrollments, update-enrollment, delete-enrollment, bulk-create, search-emails, get-enrollment) and extended; Open Questions and Out of Scope retained with resolution notes; References and Version History added. Summary of PRs: #706, #718, #790, #869, #871, #875.

  • 1.0 — 2026-06/07 — Joshua Uriel Tribiana. Original Hand-Off (creator learner management, manual add + bulk import, self-enrollment, progress/status tracking).


Was this article helpful?