Reset Progress

1. Front Matter

• Title: Reset Progress

• Author: Joshua Uriel Tribiana

• Reviewers: Scorvei

• Created: July 2026

• Status: Approved and Merged

• References:

  • Feature ticket: [9.5] Reset Progress

  • Related implementation files:

    • app/api/learner/reset-quest/route.ts

    • components/learner/ResetQuestDialog.tsx

    • components/learner/QuestPlayer.tsx

    • components/learner/dashboard/ActiveQuestsList.tsx

2. Introduction & Goals

Problem Summary

Learners may need to restart a quest after changing goals, reattempting content, or correcting an incorrect progression state. The product needed a safe and explicit way to clear persisted progress without manual support.

Goals

• Allow authenticated learners to reset their own quest progress from the UI.

• Reset progress in a controlled and reversible-by-design manner.

• Ensure reset only applies to an existing enrollment tied to the authenticated learner.

• Keep the reset operation simple and explicit for the user.

Non-Goals

• Bulk reset across multiple quests.

• Resetting other systems such as analytics, activity logs, or creator-side records.

• Creating a full audit trail for reset events.

Glossary

• Enrollment: The learner-to-quest relationship stored in the database.

• Progress Payload: The JSON object stored in the enrollment record that tracks completion state.

• Reset Flow: The confirmation dialog and API call used to clear progress.

3. High-Level Architecture

System Diagram

                    LEARNER RESET QUEST FLOW
 
+--------------------------+
| Learner UI               |
+--------------------------+
            |
            v
+--------------------------+
| ResetQuestDialog         |
+--------------------------+
            |
            v
+----------------------------------+
| POST /api/learner/reset-quest    |
+----------------------------------+
            |
            v
+--------------------------+
| authenticateUser         |
+--------------------------+
            |
            v
+-------------------------------+
| Supabase                      |
| quest_enrollments             |
+-------------------------------+
            |
            v
+-------------------------------+
| Update progress payload       |
+-------------------------------+
            |
            v
+-------------------------------+
| Success / Error response      |
+-------------------------------+
            |
            v
+--------------------------+
| Learner UI               |
+--------------------------+

Technologies Used

• Next.js / React / TypeScript

• Supabase

• Zod for request validation

• Sonner for toast feedback

• shadcn/ui dialog and button components

4. Detailed Design & Implementation

Data Model / Schema

The feature does not introduce a new table. It updates the existing enrollment record in the quest_enrollments table.

Relevant fields:

• quest_id

• learner_id

• progress

• status

The progress payload is reset to this shape:

{
  "percentage": 0,
  "visited_cards": [],
  "last_visited_at": null
}

API Specification

Endpoint

• POST /api/learner/reset-quest

Request Body

{
  "quest_id": "uuid"
}

Validation

• quest_id must be a valid UUID.

Authentication

• Requires an authenticated learner session.

Response

Success:

{
  "success": true,
  "data": {
    "progress": {
      "percentage": 0,
      "visited_cards": [],
      "last_visited_at": null
    }
  }
}

Error:

{
  "success": false,
  "message": "Enrollment not found"
}

Logic & Workflow

1. The learner opens the reset option from either the quest player or the learner dashboard.

2. The UI opens a confirmation dialog.

3. The learner must type RESET to enable the destructive action.

4. The frontend sends a POST request with the selected quest_id.

5. The backend authenticates the learner and verifies that the learner is enrolled in the target quest.

6. The backend updates the enrollment progress payload to zeroed values.

7. The UI shows a success or error toast.

5. Infrastructure & Operations

Dependencies

• Learner authentication via the shared auth layer

• Supabase access to the quest_enrollments table

• Existing quest progress model stored in enrollment data

Monitoring & Alerting

• Errors are surfaced through server logs using console error output.

• Frontend shows user-facing toasts for failures.

• No dedicated alerting or metrics pipeline is currently implemented for reset-specific events.

Deployment Plan

• No database migration is required.

• Deploy the updated API route and frontend dialog components together.

• Validate that reset works for an enrolled learner and is rejected for non-enrolled or invalid requests.

6. Testing & Quality Assurance

Test Strategy

• Manual UI verification for both entry points:

  • quest player

  • dashboard

• API validation check for invalid request payloads

• Enrollment access check for authenticated learners

Known Limitations

• The reset action currently only clears the progress payload and does not clear other related learner artifacts.

• There is no reset history or audit trail yet.

• The reset UI is not available in all quest contexts.

7. Maintenance & Support

Troubleshooting

• Reset button is disabled: The learner has not typed RESET in the dialog.

• API returns 404: The learner is not enrolled in the requested quest.

• API returns 400: The request body is invalid or missing the required UUID.

• Reset succeeds but progress still appears: The UI may need a refresh or a callback to rehydrate the learner state.

Changelog

• 1.0 - Draft: Initial implementation added for learner-driven quest reset flow, July 2026.