Front Matter
Title: Activity Cards
Author: Krizha Onise Cortez (armaminter)
Updated by: Patrick Babala
Reviewers: Joylynne Grace Esportuno (teruterubozuuu), Jethro Lagmay (dyorgie), Sean Patrick Caintic (scorevi)
Created: January 2026
Last Updated: September 30, 2026
Status: Published
References:
Issue: [3.3 Activity Cards] — https://github.com/wyzlab/WyzQuests/issues/73
Sub-issues addressed in Revision 2.0 (per PR branch names / bodies): #15, #16, #17 — Activity Card code-block, modal-dismiss, and preview fixes (PR #708); #20, #21 — Learner Activity Card refinement (PR #701).
Milestone: [3] Develop (Content Production)
Related documents: Hand-Off Documentation — Activity Cards; Internal Technical Guide — Visual Canvas
Introduction & Goals
Problem Summary:
The Activity Cards module provides a reusable assessment system that allows creators to build interactive learning activities consisting of multiple question types. Activities may be created independently through the Question Hub and later embedded into quests, or authored directly as custom questions within Quest Activity Cards.
The module supports configurable quiz settings, automated grading, learner submissions, randomized questions and answer choices, timer-based assessments, and integration with the Form Editor and Visual Canvas. It enables creators to reuse assessments across multiple quests while maintaining a consistent learner experience.
Revision 2.0 hardened the Question Hub authoring experience (card-type selector, asset picker, create-activity validation), polished the learner-facing cards (removed type pills, stale default titles, and muted text), and fixed modal/editing friction in the quest editors (Add Question modal, question-source tab switching, code-block templates, card previews, and canvas node menus).
Goals & Non-Goals:
Goals:
Question Hub
Allow creators to create reusable learning activities.
Support multiple assessment question types.
Allow creators to edit, delete, reorder, and organize questions.
Support configurable quiz settings.
Store reusable activities independently from quests.
Quest Integration
Allow Quest Activity Cards to reference Question Hub activities.
Allow creators to create custom activity questions directly inside a quest.
Synchronize Activity Cards between the Form Editor and Visual Canvas.
Learner Experience
Display interactive question cards.
Support automatic grading.
Track quiz attempts.
Support timers and randomized questions.
Display activity results immediately after submission.
Non-Goals:
Activity Cards do not currently support collaborative editing.
Activities do not currently support manual grading for essay questions.
Activities do not generate email or push notifications.
Activity questions cannot currently contain nested activities.
Reflection questions are not currently available as selectable Question Hub cards. (Still true in Revision 2.0 — the card-type selector exposes six types; the Reflection card component and
reflectionhandling remain in the codebase, but the type was removed from the selector in PR #682.)Activity Cards do not currently support importing questions from external assessment formats.
Glossary:
Activity — A reusable collection of assessment questions managed through Question Hub.
Question Card — An individual assessment item within an activity.
Activity Card — A Quest content card that embeds either a reusable activity or custom questions.
Question Hub — Creator workspace for managing reusable activities.
Custom Questions — Questions authored directly inside a Quest Activity Card without using Question Hub.
Quiz Mode — Activity mode that enables grading, passing scores, retake limits, and submission tracking (
activity_type = 'quiz').Activity Mode — Ungraded activity mode that allows unlimited attempts without storing quiz submissions (
activity_type = 'activity').Activity Submission — Learner responses and grading results stored after completing a quiz.
Question Randomization — Random ordering of questions during learner sessions.
Option Randomization — Random ordering of answer choices within supported question types.
Image Map — Question type that requires learners to identify regions on an uploaded image.
High-Level Architecture
System Diagram:
The Activity Cards System centers around the Question Hub, where creators build reusable activities composed of question cards. These activities are persisted in the
activitiesandquestionstables, consumed by the Form Editor and Visual Canvas, and later delivered to learners through the learner activity APIs, with quiz submissions stored separately inactivity_submissions.The original vertical flowchart has been replaced with a layered architecture diagram built from the current code.
Technologies Used:
Next.js App Router
React
TypeScript
Supabase
Supabase Auth (Revision 2.0 — replaced Clerk; all activity routes resolve the session through
getCreatorAuthContext()/authenticateUser())Zod
TailwindCSS
Sonner
Supabase Storage
The system also reuses shared application services including authentication helpers, asset upload endpoints, validation schemas, shared learner grading utilities, and Visual Canvas synchronization utilities.
Detailed Design & Implementation
Data Model / Schema:
Schema note. The
activities,questions,activity_submissions, andquest_content_cardstables have noCREATE TABLEmigration in this repository (they were provisioned outside the migration history). Column lists below are inferred from the current APIselect/insertstatements and from the in-repoALTER TABLEmigrations.asset_metadataand the later column additions toquestionsdo have migrations. Verify against the live database before relying on exact types/constraints.activities
Stores reusable Question Hub activities created by creators. Each activity serves as a container for multiple question cards and configurable assessment settings.
Relevant fields:
idcreator_idtitledescriptionactivity_type—'activity'|'quiz'banner_colorbanner_image_urlgrading_settings(jsonb)max_retakesshow_correct_answersshow_scorerandomize_questionsrandomize_optionstime_limit_minutescreated_atupdated_at
Example:
{"title": "Basic Programming Quiz","activity_type": "quiz","show_score": true,"randomize_questions": true,"time_limit_minutes": 30}
questions
Stores every question card belonging to an Activity.
Relevant fields:
idactivity_idcreator_idsort_ordertypetextansweroptions(jsonb)image_urlbackground_imagebackground_audioreflection_promptsettings(jsonb — essay/reflection word limits, default{"minWords": 0, "maxWords": null})created_atupdated_at
Supported Activity Card types (Question Hub selector —
components/activity/CardTypeModal.tsx):Multiple Choice
Checkbox
True / False
Identification
Essay
Image Map
Revision 2.0 caveat (verify against live DB). The only in-repo type constraint migration,
supabase/migrations/20260323_fix_questions_type_check_constraint.sql, enumerates five types (multiple-choice,checkbox,true-false,identification,image-map) and does not includeessayorreflection. The ZodquestionSchemainshared/schemas/activitySchema.ts:11matches those five, while theQuestiontype intypes/creator.d.ts:141also includesreflectionandessay. The Question Hub selector offers Essay, andPOST /api/creator/update-questionsacceptsessay/reflection, so the livequestions_type_checkconstraint must be confirmed before relying on hub-level essay/reflection persistence.Example:
{"activity_id": "...","type": "multiple-choice","text": "What is HTML?","options": ["...", "...", "..."],"answer": "HyperText Markup Language"}
quest_content_cards
Stores Activity Cards when embedded inside a Quest through the Form Editor.
Relevant fields:
id— text (changed from uuid in20260716_change_content_card_id_to_text.sql)quest_idtype— one oftext,activity,reflection,scenario,image,video,audio,file,link,codeblock,discussion,questioncontent(jsonb)motivation(jsonb)order_indexcreated_atupdated_at
Activity Card
contentstores:activity_idquestionSource—'custom'|'hub'questionstitle
activity_submissions
Stores learner quiz attempts.
Relevant fields:
idlearner_idactivity_idquest_idcontent_card_id— text, FK →quest_content_cards(id)answers(jsonb)scoretotal_questionspercentagepassedfeedbacksubmitted_atcreated_at
Quiz submissions are only stored when the Activity Type is configured as Quiz.
asset_metadata
Stores uploaded activity banner images and Image Map assets (and other creator assets). Created by
supabase/migrations/20260424053322_create_asset_metadata_table.sqlwith soft-delete support.Relevant fields:
idcreator_id(text)file_namefile_pathfile_urlexternal_urlfile_typefile_sizeasset_type—IMAGE|AUDIO|VIDEO|quest_profile|quest_mentor|adventure-profile(+DOCUMENTper20260813_add_document_asset_type.sql)usage_context— e.g.activity:preview-bannersource—uploaded|externalthumbnail_urldeleted_at,expires_at(soft delete / auto-purge)created_at,updated_at
RLS note.
asset_metadatahas owner-scoped RLS policies (auth.uid()/ JWTsub), rewritten in20260911_supabase_rls_auth_uid.sql. No RLS policies foractivities,questions,quest_content_cards, oractivity_submissionsexist in this repository — the activity routes use the server Supabase client and enforce ownership in application code (getCreatorAuthContext+verifyAgencyResourceOwnership). Confirm live RLS before exposing these tables directly.
API Specification:
Existing routes below were corrected to match the current code.
PUT/DELETEmethods for quest-content-cards and the removedupload-mediaroute are noted explicitly.Activity Management APIs
GET /api/creator/list-activities— Returns all activities owned by the authenticated creator, including their ordered questions. (The original guide pointed at/api/creator/quest-content-cards/listhere, which lists quest content cards, not activities — corrected.)POST /api/creator/create-activity— Creates a new Question Hub activity after validating activity settings and banner information (multipart/form-data; raster-image-only banner validation).GET /api/creator/get-activity— Retrieves an existing activity together with its configuration.PUT /api/creator/update-activity— Updates an existing activity, including settings and banner replacement/removal.DELETE /api/creator/delete-activity— Deletes an activity together with its associated question cards and cleans up the banner asset.
Question Card APIs
GET /api/creator/list-question-cards— Retrieves every question belonging to an activity, ordered bysort_order.POST /api/creator/update-questions— Creates, updates, and removes question cards within an activity. Incomplete cards are skipped (not rejected): the route filters them and returnsskippedCountin the response.PUT /api/creator/reorder-questions— Updates the ordering of question cards after drag-and-drop operations.
Quest Activity Card APIs
GET /api/creator/quest-content-cards/list— Retrieves Activity Cards embedded inside a Quest. In linear mode, card order is taken fromcanvas_metadata.POST /api/creator/quest-content-cards/create— Creates a new Activity Card inside the Form Editor and syncs it to the canvas.PUT /api/creator/quest-content-cards/update— Updates an existing Activity Card (PUT, notPOST).DELETE /api/creator/quest-content-cards/delete— Removes an Activity Card from a Quest (DELETE). Returns409 HAS_SUBMISSIONSwhen the card has learner submissions.PUT /api/creator/quest-content-cards/reorder— Updates the ordering of Quest content cards (PUT).POST /api/creator/convert-canvas-to-cards— Synchronizes Visual Canvas Quiz nodes into publishable Activity Cards (skips when cards already exist).POST /api/creator/quest-content-cards/upload-motivation-media— Uploads motivation image/video/gif/audio for a card.
Learner APIs
GET /api/learner/get-activity-questions— Retrieves activity questions and assessment settings for learners. Applies seeded question/option shuffling and verifies the activity is linked to a published quest (viaquest_content_cardsorcanvas_metadata).POST /api/learner/submit-activity-answers— Grades learner answers, stores quiz submissions when applicable, updates learner quest progress, and returns grading results.GET /api/learner/get-activity-submission— Returns the learner's latest quiz submission.GET /api/learner/get-retake-status— Returns remaining retake availability for quiz activities.GET /api/learner/quest-content-cards— Lists ordered content cards for a published quest (learner view).
Asset Upload APIs
POST /api/creator/upload-assets— Uploads Image Map images and activity/banner assets to Supabase Storage (public-assets) and recordsasset_metadata.POST /api/creator/quest-content-nodes/get-upload-url— Returns a signed Supabase upload URL for quest content-node media (signed-URL flow).DELETE /api/creator/quest-content-nodes/delete-media— Deletes specific node media objects or the whole node folder.Removed:
POST /api/creator/quest-content-cards/upload-media— replaced by the signed-URL flow (quest-content-nodes/get-upload-url) andquest-content-cards/upload-motivation-media.
Logic & Workflows:
Activity Creation Workflow
Creator opens the Question Hub.
Creator creates a new activity.
Activity information is validated (title required; banner is a raster image only — SVG rejected to prevent stored XSS).
Banner images are uploaded as a Buffer with a server-validated content type when provided.
The activity is saved into the
activitiestable (quiz mode requires a passing score; activity mode forcesmax_retakes/passing_scoretonull).The Activity List refreshes automatically.
Question Card Management Workflow
Creator opens an Activity.
Existing Question Cards are retrieved.
Creator adds, edits, deletes, or reorders question cards (the Card Type selector offers six types; Reflection is not selectable).
Client validates required fields based on card type.
Updated cards are submitted through the Question Card API.
The API validates ownership and question data; incomplete cards are skipped and reported via
skippedCount.Questions are inserted, updated, or deleted from the database.
Updated Question Cards are returned to the editor.
Quest Activity Card Workflow
Creator opens the Form Editor.
Creator inserts an Activity Card.
The card can reference an existing Question Hub activity (
questionSource: 'hub') or use custom questions (questionSource: 'custom'). Switching the source tab preserves in-progress questions (PR #708).Activity configuration is synchronized into
quest_content_cards.For linear quests, changes are synchronized to the Visual Canvas metadata (
lib/canvas-sync/formToCanvas.ts,lib/canvas-sync/canvasToForm.ts).Published quests expose the Activity Card to learners.
Learner Activity Workflow
Learner opens a published quest.
Activity questions are retrieved.
Activity settings determine question randomization, option randomization, timers, and grading behavior.
Learner answers all questions.
Submission is validated.
The grading engine evaluates each answer.
Quiz submissions are stored when applicable (
activity_type = 'quiz').Learner quest progress is updated (content card marked visited).
Results are displayed to the learner.
Visual Canvas Synchronization Workflow
Activity Cards inside the Form Editor are represented as Quiz Nodes in the Visual Canvas.
Custom questions and Question Hub references are synchronized between both editors.
Canvas publishing converts Quiz Nodes into Quest Content Cards.
Published quests use the synchronized content during learner execution.
Revision 2.0 — Engineering Changes
PR #682 — Question Hub activity cards & Image Map bug fixes
Removed Reflection from the Question Hub
CardTypeModalselector (six selectable types remain).Fixed the squished/overflowing asset grid in
BackgroundSelectorModal(auto-rows-maxwith a scroll container).Fixed
POST /api/creator/create-activityrejecting valid payloads: optional Zod fields receivednull; the route now passesundefinedfor absentsettingsand normalizesactivity_type.Fixed the create-activity client unwrapping the nested API response (
result.data || result).Removed strict Image Map region validation from
POST /api/creator/update-questions; the server now only requiresimage_urlfor image-map cards, preventing a valid question from disappearing when its regions were incomplete client-side.
PR #701 — Learner Activity Card refinement
Removed the type pills/labels from learner question cards (
LearnerQuestionLayoutnow shows only the question number plus background/audio indicators).Removed stale default card titles such as "New Quiz Card" from the learner intro (
ActivityCardContentfilters default titles).Changed Reflection renderer body text from muted grey to the default text color.
PR #708 — Modal, code-block, preview, and canvas fixes
Added dismiss guards to the shared Add Question modal and card-type selection modal (
onPointerDownOutside/onEscapeKeyDownpreventDefault) so editing is not lost on accidental outside clicks.Fixed question-source tab switching wiping questions on the Activity Card editor (
handleQuestionSourceChangeno longer resets state).Added a Templates view mode to the Codeblock card editor and the scenario Code child card (shared
lib/utils/template-helpers.tsx).Fixed the canvas node triple-dot action menu (pointer-down propagation,
align="end",sideOffset).Fixed the Form Editor card preview for codeblock/video/image/audio/file/link/reflection/discussion/question types; custom Activity Cards now show their question count instead of "No quiz selected".
Cumulative canvas layout engine,
ReorderContextepoch-keyed Monaco remount (fixes anInstantiationServicecrash), and asset grid scroll on the visual canvas. (Cross-referenced with the Visual Canvas internal technical guide.)
Infrastructure & Operations
Dependencies:
Dependency
Notes
Supabase
Stores activities, questions, submissions, and quest content
Supabase Auth
User authentication and authorization (
getCreatorAuthContext,authenticateUser) — replaces ClerkZod
Shared validation schemas (
shared/schemas/activitySchema.ts)Sonner Toast
Success and error notifications
Supabase Storage
Activity banners, Image Map images, and card media (
public-assets)Visual Canvas
Synchronizes Quiz Nodes with Activity Cards
React controlled state
Activity and question dialogs use
useState, not React Hook FormReact Dropzone
Not used by the Activity Cards module (uploads use native file inputs and Supabase Storage)
Monitoring & Alerting:
The Activity Card System validates all creator and learner requests before database operations.
Validation includes:
Activity title validation
Activity settings validation
Question type validation
Answer validation
Image Map image validation (server requires
image_url; region geometry is validated client-side during authoring — PR #682)Quiz submission validation
Learner enrollment validation
Banner/asset upload validation (raster-only, size/duration caps)
Current implementation relies primarily on API responses and server logs to monitor:
Activity creation failures
Activity update failures
Question save failures
Question reorder failures
Asset upload failures
Learner submission failures
Grading failures
Canvas synchronization failures
Deployment Plan:
Execute required database migrations.
Verify Row Level Security (RLS) policies.
Deploy Question Hub pages.
Deploy Activity Builder pages.
Deploy Form Editor updates.
Deploy learner Activity Card components.
Deploy updated API routes.
Verify banner uploads and Image Map uploads.
Verify Activity Card creation and editing.
Verify learner quiz submissions.
Verify Visual Canvas synchronization.
Promote changes to staging after successful validation.
Testing & Quality Assurance
Test Strategy:
Activity Management
Create activity
Edit activity
Delete activity
Activity settings validation
Banner upload
Question Cards
Create question
Update question
Delete question
Reorder questions
Card type conversion
Image Map validation
Learner
Activity loading
Quiz submission
Grading
Retake limits
Randomization
Timer expiration
Integration
Form Editor synchronization
Visual Canvas synchronization
Publishing workflow
Activity submission persistence
Revision 2.0 — automated coverage. No automated tests directly exercise the Activity Cards grading engine (
lib/grading/gradeActivity.ts), activity submissions/retakes, learner Activity Card rendering, or the activity API routes. Existing coverage is adjacent:tests/e2e/creator/scenario-logic.spec.tsandtests/e2e/creator/standalone-question-node.spec.tsexercise Question/Quiz nodes in the player,tests/unit/validate-quiz-submission.test.tsandtests/unit/forum-and-learner.schema.test.tscover quiz-submission schema parsing (including image-map{x,y}payloads), andtests/creator/utils/canvas-import.test.tscovers the AI canvas-import path that generates activity/quiz children. Treat the checklist above as manual QA until unit coverage is added.Known Limitations:
Reflection cards exist internally but cannot currently be added through the Question Hub interface.
Essay and Reflection responses require manual evaluation in the hub path and are not automatically graded (
gradeQuestionreturnsfalseforessay/reflection; the canvasgradeQuizQuestionpath auto-passes an in-range essay by word count only).The in-repo
questions_type_checkconstraint lists five types and omitsessay/reflection— confirm the live constraint (see Data Model note).Activities are only available to learners after the associated quest is published.
Real-time collaborative editing is not supported.
Activity analytics are limited to current submission data.
Offline activity completion is not supported.
No automated test coverage for grading, submissions, retakes, or activity routes (see above).
Maintenance & Support
Troubleshooting:
Activity cannot be created
Verify required fields are completed.
Verify activity title is valid.
Verify creator permissions.
Verify database connection.
For quiz mode, verify a passing score is set; for activity mode, verify no passing score/retake limit is sent.
Question cards cannot be saved
Verify all required question fields are completed.
Verify at least one correct answer exists.
Verify Image Map images are uploaded (regions are validated client-side before save).
Verify activity ownership.
Check the
skippedCountvalue in theupdate-questionsresponse — incomplete cards are silently skipped.
Learner cannot submit activity
Verify learner is enrolled.
Verify activity belongs to the quest.
Verify retake limit has not been exceeded.
Verify required answers are present.
Activity results are incorrect
Verify grading configuration.
Verify correct answers.
Verify grading settings.
Verify activity type configuration.
Visual Canvas does not synchronize
Verify Quiz Nodes are connected correctly.
Verify Form Editor synchronization completed.
Verify content card conversion succeeded before publishing.
Question-source tab switch or Add Question modal misbehaves (Revision 2.0)
Confirm the Add Question / card-type modals use the dismiss guards; accidental outside clicks should not close them.
Switching between Custom and Hub question sources should preserve in-progress questions.
Changelog:
v1.0 (March 2026) — Initial implementation of the Activity Card System supporting reusable Question Hub activities, Activity Cards, learner submissions, grading, Form Editor integration, and Visual Canvas synchronization.
v2.0 (September 2026) — Engineering overhaul (PRs #682, #701, #708): Question Hub card-type/asset/create-activity fixes; learner card de-cluttering (type pills, default titles, grey text); Add Question modal dismiss guards; question-source tab-switch fix; code-block Templates view; Form Editor card-preview fixes; canvas node menu and cumulative layout fixes; guide re-verified against the codebase (Clerk → Supabase Auth, endpoint corrections); system diagram re-created as a layered architecture.
Document version:
2.0 - Published, Revision 2.0 overhaul: re-verified against current code, added Revision 2.0 engineering changes (PRs #682, #701, #708), corrected auth/endpoint/schema references, refreshed troubleshooting and version history, re-created layered architecture diagram, 09/30/2026.
1.1 - Published, Initial internal technical guide for the Activity Card System, July 2026.
1.0 - Draft, Feature pushed to dev server after initial dev review, 03/03/2026