Social Debrief

Feature Owner : Joylynne Esportuno
Module : Deliver (Export)
Priority : P4
Sprint #7: Fully Implemented
Date : July 2, 2026

EXECUTIVE SUMMARY

What is this feature ?
Social Debrief embeds a forum-backed discussion prompt into the quest player through discussion nodes.

Why does it matter ?
Learners need a place to reflect socially after content or decisions.

What's the MVP scope ?
Internal discussion nodes create forum posts and embed them in player. Grading participation is out of scope.

1. USER PAIN POINT & SOLUTION

Current State

Learner reflection can be isolated from peer discussion.

Pain Point

Emotional : Learners miss peer context.
Functional : Discussion requires leaving quest flow.
Business Impact : Lower engagement and social learning.

Future State

Learners discuss inside an embedded forum thread.

Marketing Hook

"Turn reflection points into shared learning conversations."

2. 4D FRAMEWORK MAPPING

Diagnose

Shows where learners need discussion after decisions.

Design

Adds debrief prompts to quest paths.

Develop

Creates forum posts from discussion nodes.

Deliver

Embeds forum conversation in Quest Player.

3. USER FLOWS

Entry Point

Discussion node in quest editor/player.

Success Criteria

Learner sees embedded forum post and can comment/reply.

Main Flow

1. Creator adds internal discussion node.

2. Save/publish creates forum post if missing.

3. forumPostId is saved in canvas metadata.

4. Learner reaches discussion node.

5. Player embeds PostDetail.

Edge Cases

• No forumPostId : Show discussion unavailable state

• API error : Forum actions show error

• Permission denied : Require authenticated forum access

Decision Points

• IF internal thread enabled, embed WyzQuests forum

• ELSE show external discussion link

4. INFORMATION ARCHITECTURE

Primary Information

• Discussion title

• Prompt/body

• Comments

Secondary Information

• Replies

• Likes

Tertiary Information

• Forum author metadata

Actions

Primary CTA : Comment
Secondary Actions : Reply, like, view in forum

5. WIREFRAMES

Excluded — Feature fully implemented.

6. WIREFLOWS

Excluded — Feature fully implemented.

7. PROTOTYPE

Excluded — Feature fully implemented.

8. BACKEND SCHEMA

Database Tables

• forum_posts

• forum_comments

• forum_replies

• forum_likes

• quests.canvas_metadata.nodes[].data.forumPostId

Indexes

create index on forum_posts(user_id);
 
create index on forum_comments(post_id);
 
create index on forum_comments(user_id);
 
create index on forum_replies(comment_id);
 
create index on forum_replies(user_id);
 
create index on forum_likes(post_id);
 
create index on forum_likes(user_id);
 
create index on forum_comment_likes(comment_id);
 
create index on forum_comment_likes(user_id);
 
CREATE INDEX IF NOT EXISTS idx_forum_reply_likes_reply_id ON forum_reply_likes(reply_id);
 
CREATE INDEX IF NOT EXISTS idx_forum_reply_likes_user_id ON forum_reply_likes(user_id);

Constraints

• Internal discussion nodes require a valid forumPostId to render embedded forum content.

• Comment/reply body must pass schema validation.

• Forum post creation should only happen for authorized quest editors.

9. API ENDPOINTS

Endpoint 1: POST /api/forum/create-post

Purpose: Creates the internal forum thread for a discussion/debrief node.
Auth: Authenticated creator/editor during save/publish flow.
Request Data: Title and discussion prompt/body.

Endpoint 2: GET /api/forum/get-post?id=

Purpose: Loads the forum post embedded in the Quest Player.
Auth: Authenticated forum access.
Response Data: Post, author metadata, like count, and comment count.

Endpoint 3: GET /api/forum/get-comments

Purpose: Loads post comments for the embedded/full forum view.
Auth: Authenticated forum access.

Endpoint 4: POST /api/forum/create-comment

Purpose: Adds a learner comment to the debrief post.
Auth: Authenticated user.
Request Data: Post ID and comment body.

Endpoint 5: POST /api/forum/create-reply

Purpose: Adds a reply to an existing forum comment.
Auth: Authenticated user.
Request Data: Comment ID and reply body.

10. DATA REQUIREMENTS

Frontend Needs

• Discussion node title, prompt, external link, and internal-thread flag.

• forumPostId stored in canvas metadata.

• Forum post body, author, created date, like count, and comment count.

• Comment/reply lists and draft input state.

• Embedded vs full forum view state.

Backend Needs

• Authenticated creator ID for creating the post during save/publish.

• Authenticated learner/user ID for comments, replies, and likes.

• Forum post ID mapped back to the discussion node.

API Calls Frontend Will Make

• Create forum post during save/publish when missing.

• Load forum post/comments in player.

• Create comments/replies from embedded forum UI.

Caching Strategy

• Cache post data only for the current view/session. Refetch comments after new comment/reply actions.

11. PERFORMANCE CONSIDERATIONS

Database Optimization

• Forum post/comment queries should filter by post ID and paginate comments/replies for long threads.

Client Optimization

• Do not load forum data for all discussion nodes upfront. Load only when the learner reaches a debrief node.

Caching Strategy

• Keep the embedded post in component state while the learner remains on that node. Invalidate comments after mutations.

API Response Time

• Embedded forum post should load quickly enough that the quest player does not feel blocked. Show skeleton/loading state for comments.

12. SECURITY & AUTHORIZATION

Who Can Access This Feature?

• Creator:

  • Can configure discussion nodes and create internal threads.

  • Can view/comment when they can access the quest/forum.

  • Can create a post

• Learner:

  • Can view/comment when they can access the quest/forum.

  • Can create a post

Authorization Logic

• Creating the post on a discussion node should be tied to an authorized quest edit/save flow. Commenting/replying requires authenticated forum access.

13. ERROR HANDLING

Common Errors

401 Unauthorized: Prompt learner to sign in before commenting/replying. If viewing is allowed but interaction requires auth, keep the thread readable where policy permits.

403 Forbidden: Show access denied if the user cannot access the quest or forum post.

404 Forum Post Not Found: Show "Discussion not available" in the player and provide a creator-facing hint that the forum post may need to be created again.

500 Server Error: Show retry message for forum actions and avoid duplicating comments/replies on retry.

14. TESTING CHECKLIST

Happy Path

• Internal discussion post created

• forumPostId saved

• Embedded post loads

• Comment/reply works

• External link mode still works

Edge Cases

• Missing forumPostId shows unavailable state

• Invalid/empty comment is rejected

• Deleted forum post does not crash player

• Forum post creation failure is surfaced to creator

15. OPEN QUESTIONS

For Frontend:

• Should forum participation complete the node?

• Should decision paths require learners to view or post in debrief before continuing?

For Backend:

• Should discussion participation be stored in learner progress?

• Should debrief/forum notifications be scoped to quest participants only?

16. OUT OF SCOPE

• Participation grading

• External forum comment sync.

17. SUCCESS METRICS

• Comment rate

• Debrief engagement

18. DEPENDENCIES

This feature depends on:

• Forum APIs

• Discussion node authoring

• Quest Player discussion renderer

• Canvas metadata persistence for forumPostId

These features depend on this:

• Scenario Logic debrief paths

• Learner social learning workflows

• Forum engagement notifications

19. TIMELINE & OWNERSHIP

Backend: Joylynne Esportuno
Frontend: Joylynne Esportuno
QA: Uriel Tribiana
Estimated Completion: Fully implemented