[4.3] Social Debrief

Author name: Joylynne Grace C. Esportuno
Reviewers: Uriel Tribiana
Creation Date: April 20, 2026
References: https://github.com/wyzlab/WyzQuests/issues/43
Status: Approved and Merged

INTRODUCTION & GOALS

Problem Summary

Social Debrief lets learners discuss a quest prompt inside the forum experience. In the quest player, a discussion node can embed an internal forum thread so learners can comment, reply, and continue the learning conversation without losing quest context. Decision nodes support this feature by routing learners through branching paths that may lead to different discussion or reflection moments.

Goals

• Let creators add discussion/debrief nodes to quest content.

• Support internal forum threads through forum_posts.

• Embed the forum post in the learner quest player.

• Preserve the forum post ID on the canvas node for repeatable rendering.

• Allows the creator to choose between two internal forum types: “Forum Link” and “Create Post”

• Allow decision-based quest paths to lead learners into debrief nodes.

Non-Goals

• This feature does not create a separate social-debrief database table.

• This feature does not currently grade forum participation.

• Deleting a Discussion Node with a forumPostId does not delete the post on the forum page.

Glossary

• Social Debrief — A quest discussion point backed by the forum system.

• Discussion Node — Canvas node used to configure internal or external discussion prompts.

• Internal Thread — A WyzQuests forum post embedded in the quest player.

• Forum Post ID — forumPostId stored on a discussion node after forum post creation.

• Internal Forum Types:

  • Forum Link — Allows creators to embed a WyzQuests forum link to a Discussion Node.

  • Create Post — When a quest is published, the discussion node will automatically create a post on the Forum page along with the Discussion prompt and title.

HIGH-LEVEL ARCHITECTURE

System Diagram

Technologies Used

• Next.js,TypeScript, Supabase, Zod, Existing forum components, and React Flow canvas nodes

DETAILED DESIGN & IMPLEMENTATION

Data Model / Schema

Social Debrief uses existing forum and quest canvas storage.

• quests.canvas_metadata : Stores canvas nodes, edges, and discussion node forumPostId.

• forum_posts : Stores the internal debrief thread title/body.

• forum_comments : Stores learner comments on a debrief thread.

• forum_replies : Stores nested replies to comments.

• forum_likes, forum_comment_likes, forum_reply_likes : Store forum engagement.

Discussion node schema fields:

• discussionPrompt : Prompt shown to learners and used as the forum body.

• externalLink : Optional external discussion URL when not using internal forum mode.

• enableInternalThread : Enables embedded WyzQuests forum mode.

• forumPostId: UUID of the generated forum_posts record.

API Specification

Forum create-post payload is submitted as FormData with a json field:

{
 
  "title": "Quest Discussion",
 
  "body": "What decision would you make and why?"
 
}

Logic & Workflows

1. Creator adds a Discussion node in the visual canvas or form editor.

2. Creator chooses internal thread mode enableInternalThread = true.

3. Creator chooses a forum type between “Forum Link” and “Create Post”

4. On save/publish, useEditorActions scans discussion nodes missing forumPostId.

5. For each missing internal thread, the app calls /api/forum/create-post.

6. The returned forum post ID is written back to the discussion node in quests.canvas_metadata.

7. Learner reaches the discussion node in the quest player.

8. DiscussionRenderer embeds PostDetail using forumPostId.

9. Learner comments, replies, and likes through normal forum APIs.

10. If the quest path includes decision nodes, learner choices determine whether and when they reach the debrief node.

Infrastructure & Operations

Dependencies

• Clerk/auth helper through authenticateUser.

• Supabase forum tables.

• Existing quest canvas metadata APIs.

• Existing forum UI components.

Monitoring & Alerting

Current monitoring is application/log based:

• createForumPostsForDiscussionNodes logs canvas save failures.

• Forum API routes return structured ApiResponseHelper errors.

• Recommended alerts:

  • Elevated /api/forum/create-post 5xx rate.

  • Elevated /api/forum/get-post 404/5xx rate from embedded quest player.

  • Canvas save failures after forum post creation.

Deployment Plan

1. Verify forum tables exist in the target Supabase environment.

2. Deploy frontend and API route changes together.

3. Publish a test quest with an internal discussion node.

4. Confirm the generated forumPostId is saved in quests.canvas_metadata.

5. Confirm learner can open the embedded debrief and post a comment.

TESTING & QUALITY ASSURANCE

Test Strategy

• Unit/schema: validate discussionNodeDataSchema and forum Zod schemas.

• API: create post, get post, create comment, create reply, and like routes.

• Integration: save/publish quest creates forum posts for internal discussion nodes.

• E2E: learner reaches a discussion node from a decision path and posts a comment.

Known Limitations

• Forum post creation is triggered during editor save/publish flow, not automatically when the node is first added.

• Social Debrief participation is not counted by /api/learner/complete-node.

• Decision nodes influence navigation but do not store debrief-specific state.

• External forum links are validated heuristically and are not embedded.

MAINTENANCE & SUPPORT

Troubleshooting

• Debrief says discussion is unavailable — Confirm forumPostId exists on the discussion node in quests.canvas_metadata.

• Forum post failed to create — Check /api/forum/create-post auth, payload, and Supabase insert errors.

• Embedded post does not load — Check /api/forum/get-post?id=<forumPostId> and whether the post still exists.

• Comments fail — Check /api/forum/create-comment, post_id, and authenticated user state.

• Learner never reaches debrief — Check decision/edge routing in the quest canvas.

Changelog

• 1.0 - Approved, Initial concise technical guide for Social Debrief and decision-node relationship, 06/30/2026

Document Version

• 1.0 - Published, Initial concise technical guide for Social Debrief feature, 06/30/2026