Enrollment Alerts

Feature Owner : Joylynne Esportuno
Module : Notifications (Updates)
Priority : P4
Sprint #4 : Fully Implemented
Date : July 2, 2026

EXECUTIVE SUMMARY

What is this feature ?
Enrollment Alerts email learners when a creator enrolls them in a quest.

Why does it matter ?
Learners need timely notice that new assigned learning is available.

What's the MVP scope ?
Send transactional enrollment email after creator-driven enrollment. In-app alerts and retries are out of scope.

1. USER PAIN POINT & SOLUTION

Without Enrollment Alerts

Learners may not know they were enrolled unless they manually check the app.

Pain Point

Emotional : Missed assignments create confusion
Functional : Manual follow-up is needed
Business Impact : Lower activation and completion

Current State (Already Implemented)

Learner receives an email with quest access details.

Marketing Hook

"Automatically notify learners when new quests are assigned."

2. 4D FRAMEWORK MAPPING

Diagnose

Highlights enrollment communication gaps.

Design

Uses branded email templates.

Develop

Sends transactional email from enrollment APIs.

Deliver

Gets assigned learning in front of learners.

3. USER FLOWS

Entry Point

Creator enrollment workflow.

Success Criteria

Enrollment row is created and email send is attempted without blocking enrollment.

Main Flow

1. Creator selects learner(s).

2. API creates quest_enrollments.

3. Email template renders.

4. Email service sends alert.

Edge Cases

• No email : Enrollment succeeds; log email issue.

• SMTP error : Do not roll back enrollment.

• Permission denied : Creator cannot enroll outside scope.

Decision Points

• IF email send fails, log and continue.

• ELSE learner receives enrollment email.

4. INFORMATION ARCHITECTURE

Primary Information

• Quest title

• Learner email/name

• Access link

Secondary Information

• Creator/agency branding

• Due date if available

Tertiary Information

• SMTP provider details

Actions

Primary CTA : Open quest
Secondary Actions : Contact support/admin

5. WIREFRAMES

Excluded — Feature fully Implemented

6. WIREFLOWS

Excluded — Feature fully Implemented

7. PROTOTYPE

Excluded — Feature fully Implemented

8. BACKEND SCHEMA

Database Tables

• quest_enrollments

• quests

• app_users

Constraints

• Enrollment should not be duplicated for the same learner/quest where uniqueness is enforced.

• Email should only send after enrollment creation succeeds.

• Email content must only reference quests the learner is allowed to access.

9. API ENDPOINTS

Enrollment API: /api/creator/enrollment/create-enrollment

Purpose: Creates quest_enrollments rows for selected learners.
Auth: Creator/admin access required.
Request Data: Quest ID and learner IDs/emails depending on enrollment flow.
Response Data: Enrollment success/partial failure details.

Email Service Call

Purpose: Sends the transactional enrollment alert after enrollment creation.
Auth: Server-side only.
Response Data: Provider acceptance/failure is logged, not exposed as the source of truth.

Excluded Endpoints

There is no separate public enrollment-alert endpoint. Alerts are side effects of enrollment creation so learners cannot trigger their own assignment emails arbitrarily.

10. DATA REQUIREMENTS

Frontend Needs

• Selected quest and learner list.

• Enrollment submission/loading state.

• Success and failure messages.

Backend Needs

• Learner ID, email, and display name.

• Quest ID, quest title, and learner-facing quest link.

• Creator/agency branding when available.

• Enrollment row IDs for logging/troubleshooting.

API Calls Frontend Will Make

• The frontend calls the existing enrollment API. It does not call the email service directly.

Caching Strategy

• Enrollment state should be refetched after mutation. Email delivery status is excluded from caching because no delivery audit table exists in MVP.

11. PERFORMANCE CONSIDERATIONS

Database Optimization

• Bulk enrollment should avoid one query per learner where possible. Duplicate enrollment checks should be efficient and scoped by quest/learner.

Email Throughput

• Email sending should not make bulk enrollment feel stuck. If many learners are selected, consider async processing or batched sends as follow-up.

Caching Strategy

• Do not cache enrollment mutation responses for reuse. Refetch current enrollment list after changes.

API Response Time

• Enrollment should respond as soon as rows are created and email attempts are queued/sent according to current implementation. Email failure should not make the API appear failed if enrollment succeeded.

12. SECURITY & AUTHORIZATION

Who Can Access This Feature?

• Creator: Can enroll learners within allowed scope.

• Learner: Receives email but cannot trigger creator enrollment alerts.

• Unauthenticated User: No access.

Authorization Logic

• Enrollment APIs must verify that the creator can assign the selected quest and learners. Agency/workspace boundaries must be respected where applicable.

13. ERROR HANDLING

401 Unauthorized: Prompt the creator/admin to sign in again. Do not create enrollment rows.

403 Forbidden: Show a permission message when the creator cannot enroll the selected learner or assign the selected quest.

404 Learner or Quest Not Found: Show which selected learner/quest could not be resolved when possible. For bulk enrollment, report partial failures clearly.

500 Server Error: Show a retry message. If enrollment state is uncertain, refetch enrollment data before retrying to avoid duplicates.

14. TESTING CHECKLIST

Happy Path

• Enrollment creates row.

• Email sends for valid learner.

• Email includes correct quest title and link.

• Learner can open quest from email.

Edge Cases

• Enrollment still succeeds on SMTP failure.

• Unauthorized enrollment blocked.

• Duplicate enrollment does not create duplicate alert unexpectedly.

• Missing learner email is handled safely.

15. OPEN QUESTIONS

For Frontend:

• Should creators see email delivery status after enrollment?

• Should learners also see enrollment alerts in the notification bell?

For Backend:

• Should failed email sends be retried?

• Should enrollment email delivery be written to an audit table?

16. OUT OF SCOPE

• In-app alerts

• Delivery audit table

17. SUCCESS METRICS

• Email delivery rate

• Assignment open rate

• Enrollment-to-start conversion

18. DEPENDENCIES

This feature depends on:

• Enrollment APIs

• Learner email data

• React Email templates

• SMTP/email service configuration

These features depend on this:

• Learner onboarding after creator enrollment

• Enrollment reporting and learner activation workflows

19. TIMELINE & OWNERSHIP

Backend: Joylynne Esportuno
Frontend: Joylynne Esportuno
QA: Clyde Ador
Estimated Completion: Fully implemented
Link to email environment variables: https://docs.google.com/document/d/1erLPHqCn3t-axwiwzMrzzhWJn6IWIqZxsvaVbd1sIWA/edit?usp=sharing