Feedback Modal

  1. Overview
  2. Internal Technical Guides
  3. Player
  4. Feedback Modal

1. Front Matter

  • Title: Feedback Modal

  • Author: Joshua Uriel Tribiana

  • Reviewers: Joylynne Esportuno ( teruterubozuuu )

  • Creation Date: 2026-06-29

  • Status: Approved

  • References:

    • Issue: [9.3] Feedback Modal

    • Issue: [2.3] Scenario Logic (Decision branching)

2. Introduction & Goals

  • Problem Summary
    In branching quests, when a learner makes a decision, they are immediately advanced to the next node without receiving explicit feedback on the consequences of their choice. This misses a critical instructional moment. The Feedback Modal is designed to "gate" the progression, presenting the outcome of the learner's decision before they continue, thereby reinforcing the learning objective.

  • Goals

    • Display a modal immediately after a learner selects an option in a Decision or Scenario node.

    • The modal's content (title, feedback text) will be sourced from the outcome data associated with the chosen decision branch (edge).

    • The modal will contain a "Continue" button, which is the sole method for advancing to the next node.

    • The modal will be a reusable component within the Learner Player.

    • The state for showing the modal will be managed within the main player state machine.

  • Non-Goals

    • Complex, multi-step feedback interactions within the modal itself.

    • Allowing the learner to go back and change their decision from the feedback modal.

    • Custom styling of the modal on a per-node basis.

  • Glossary

    • Feedback Modal: The UI component that displays the outcome of a learner's choice.

    • Gating: The act of preventing progression until the learner acknowledges the feedback by clicking "Continue".

    • Edge Metadata: Data stored on the connection (edge) between two nodes, which will contain the feedback content.

    • Player State Machine: The client-side logic that manages the learner's current position and state within a quest.

3. High-Level Architecture

  • System Diagram

     
     
    Creator Setup
    ─────────────
     
    +----------------------+
    | Edit Decision Edge   |
    +----------------------+
               |
               v
    +----------------------+
    | Enter Outcome Title  |
    | & Feedback Text      |
    +----------------------+
               |
               v
    +----------------------+
    | Save to Quest        |
    | Database             |
    +----------------------+
     
     
    Learner Experience
    ──────────────────
     
    +----------------------+
    | Learner Reaches      |
    | Decision Node        |
    +----------------------+
               |
               v
    +----------------------+
    | Select Choice        |
    +----------------------+
               |
               v
    +----------------------+
    | Retrieve Edge        |
    | Feedback             |
    +----------------------+
               |
               v
    +----------------------+
    | Display Feedback     |
    | Modal                |
    +----------------------+
               |
               v
    +----------------------+
    | Click Continue       |
    +----------------------+
               |
               v
    +----------------------+
    | Navigate to Next     |
    | Node                 |
    +----------------------+
               |
               └───────────────► (Repeat until quest ends)

  • Technologies Used

    • React: For building the frontend components.

    • Zustand / React Context: For the player's state management.

    • shadcn/ui: For the Dialog component that will form the base of the modal.

    • Next.js: For the API route to save quest data.

4. Detailed Design & Implementation

  • Data Model / Schema
    This feature enhances the existing canvas_metadata JSONB structure by adding data to the edges, not the nodes.

  • Edge Object Modification:
    A new data object is added to each edge originating from a Decision or Scenario node.

Property

Type

Description

outcomeTitle

string

The title displayed in the feedback modal.

feedbackText

string

The main body content of the feedback modal.

  • Example Edge JSON:

    json

    {

    "id": "edge-from-decision1-to-nodeA",

    "source": "decision-node-1",

    "target": "node-A",

    "sourceHandle": "branch-A",

    "data": {

    "outcomeTitle": "Good Choice!",

    "feedbackText": "You correctly identified the phishing attempt. This protects the company's data."

    }

    }

  • API Specification
    The feature reuses the existing API for updating a quest's canvas state. No new endpoints are required.

    • Endpoint: PUT /api/creator/update-quest-canvas

    • Logic: The creator-side editor will be modified to allow editing of edge data. When saved, the entire canvas_metadata object, including the updated edges array, is sent to this endpoint.

  • Logic & Workflows

    1. Creator Workflow (Configuring Feedback):

      • In the Visual Canvas, the creator clicks on an edge connecting a Decision node to a subsequent node.

      • An inspector panel opens, allowing the creator to input the outcomeTitle and feedbackText for that specific path.

      • On change, the client-side state for the canvas_metadata is updated.

      • A debounced save function sends the updated metadata to the PUT /api/creator/update-quest-canvas endpoint.

    2. Learner Workflow (Receiving Feedback):

      • The learner is on a Decision node and clicks a button corresponding to a specific choice/branch.

      • The onClick handler for that button calls a player state function, e.g., makeDecision(edgeId).

      • The state machine finds the edge object in the canvas_metadata that matches edgeId.

      • It reads the edge.data.outcomeTitle and edge.data.feedbackText.

      • It updates the player state: showFeedbackModal: true, feedbackContent: { title, text }, next_node_id: edge.target.

      • The FeedbackModal.tsx component, listening to this state, renders with the provided content.

      • The learner reads the feedback and clicks "Continue".

      • The modal's onContinue handler calls another state function, e.g., proceedToNextNode().

      • The state machine updates: showFeedbackModal: false, currentNodeId: next_node_id.

      • The player view updates to show the content of the new current node.

  • Key Files:

    • components/learner/player/FeedbackModal.tsx: The new, reusable modal component.

    • components/learner/player/QuestPlayer.tsx: The main player component that will house the state machine logic.

    • components/quest-editor/visual-canvas/EdgeInspector.tsx: A new component for editing edge properties in the editor.

    • app/api/creator/update-quest-canvas/route.ts: The existing API endpoint used to persist the changes.

5. Infrastructure & Operations

  • Dependencies

    • Internal: This feature is self-contained within the WyzQuests application. It depends on the existing quests table and the Visual Canvas editor.

    • External: None.

  • Monitoring & Alerting

    • No new specific monitoring is required. Standard monitoring for the quest player and the update-quest-canvas API applies.

  • Deployment Plan

    • Database Migrations: No database schema changes are required.

    • Rollout:

      1. Deploy the backend and database (no changes needed).

      2. Deploy the creator-side changes (EdgeInspector.tsx) to allow configuration of feedback.

      3. Deploy the learner-side changes (FeedbackModal.tsx and player logic).

    • This feature can be deployed directly, as it will only activate on quests that have been explicitly configured with feedback content.

6. Testing & Quality Assurance

Test Strategy

  • Unit Tests:

    • Test the FeedbackModal.tsx component to ensure it renders props correctly.

    • Test the player's state machine logic to confirm it correctly sets modal visibility and content based on makeDecision() calls.

  • Integration Tests:

    • Verify that saving edge data in the editor successfully updates the canvas_metadata in the database via the API.

  • End-to-End (E2E) / QA:

    • Creator Flow: Create a branching quest -> Click an edge -> Enter feedback text -> Save -> Refresh and confirm the feedback text is still there.

    • Learner Flow: Open the quest as a learner -> Navigate to the decision node -> Make a choice -> Confirm the feedback modal appears with the correct text -> Click "Continue" -> Confirm the player advances to the correct next node.

    • Negative Test: Make a decision on a branch with no configured feedback. Confirm no modal appears and the player advances directly.

Known Limitations

  • Feedback content is plain text only. Rich text or HTML is not supported in this version.

  • The feature is only active for Decision and Scenario nodes that produce distinct, creator-defined branches.

7. Maintenance & Support

Troubleshooting

  • Feedback modal does not appear for learner:

    1. Verify in the quest editor that the specific edge has outcomeTitle and feedbackText configured.

    2. Check the browser's developer console for any JavaScript errors in the player's state machine when a decision is made.

  • "Continue" button does not work:

    1. This indicates an issue with the player's state machine. Check the proceedToNextNode() logic for errors.

    2. Ensure the next_node_id is being correctly stored in the state when the modal is opened.

Changelog

1.0 - Approved, Technical guide created for planned feature, 2026-06-29

Written by Uriel Last updated June 29, 2026
Was this article helpful?