Activity Cards

  1. 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).

      • Revision 2.0 PRs: #682 · #701 · #708

      • Milestone: [3] Develop (Content Production)

      • Related documents: Hand-Off Documentation — Activity Cards; Internal Technical Guide — Visual Canvas

  2. 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 reflection handling 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.

  3. 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 activities and questions tables, consumed by the Form Editor and Visual Canvas, and later delivered to learners through the learner activity APIs, with quiz submissions stored separately in activity_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.

  4. Detailed Design & Implementation

    • Data Model / Schema:

      • Schema note. The activities, questions, activity_submissions, and quest_content_cards tables have no CREATE TABLE migration in this repository (they were provisioned outside the migration history). Column lists below are inferred from the current API select/insert statements and from the in-repo ALTER TABLE migrations. asset_metadata and the later column additions to questions do 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:

          • id

          • creator_id

          • title

          • description

          • activity_type — 'activity' | 'quiz'

          • banner_color

          • banner_image_url

          • grading_settings (jsonb)

          • max_retakes

          • show_correct_answers

          • show_score

          • randomize_questions

          • randomize_options

          • time_limit_minutes

          • created_at

          • updated_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:

          • id

          • activity_id

          • creator_id

          • sort_order

          • type

          • text

          • answer

          • options (jsonb)

          • image_url

          • background_image

          • background_audio

          • reflection_prompt

          • settings (jsonb — essay/reflection word limits, default {"minWords": 0, "maxWords": null})

          • created_at

          • updated_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 include essay or reflection. The Zod questionSchema in shared/schemas/activitySchema.ts:11 matches those five, while the Question type in types/creator.d.ts:141 also includes reflection and essay. The Question Hub selector offers Essay, and POST /api/creator/update-questions accepts essay/reflection, so the live questions_type_check constraint 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 in 20260716_change_content_card_id_to_text.sql)

          • quest_id

          • type — one of text, activity, reflection, scenario, image, video, audio, file, link, codeblock, discussion, question

          • content (jsonb)

          • motivation (jsonb)

          • order_index

          • created_at

          • updated_at

        • Activity Card content stores:

          • activity_id

          • questionSource — 'custom' | 'hub'

          • questions

          • title

      • activity_submissions

        • Stores learner quiz attempts.

        • Relevant fields:

          • id

          • learner_id

          • activity_id

          • quest_id

          • content_card_id — text, FK → quest_content_cards(id)

          • answers (jsonb)

          • score

          • total_questions

          • percentage

          • passed

          • feedback

          • submitted_at

          • created_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.sql with soft-delete support.

        • Relevant fields:

          • id

          • creator_id (text)

          • file_name

          • file_path

          • file_url

          • external_url

          • file_type

          • file_size

          • asset_type — IMAGE | AUDIO | VIDEO | quest_profile | quest_mentor | adventure-profile (+ DOCUMENT per 20260813_add_document_asset_type.sql)

          • usage_context — e.g. activity:preview-banner

          • source — uploaded | external

          • thumbnail_url

          • deleted_at, expires_at (soft delete / auto-purge)

          • created_at, updated_at

        • RLS note. asset_metadata has owner-scoped RLS policies (auth.uid() / JWT sub), rewritten in 20260911_supabase_rls_auth_uid.sql. No RLS policies for activities, questions, quest_content_cards, or activity_submissions exist 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/DELETE methods for quest-content-cards and the removed upload-media route 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/list here, 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 by sort_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 returns skippedCount in 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 from canvas_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, not POST).

        • DELETE /api/creator/quest-content-cards/delete — Removes an Activity Card from a Quest (DELETE). Returns 409 HAS_SUBMISSIONS when 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 (via quest_content_cards or canvas_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 records asset_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) and quest-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 activities table (quiz mode requires a passing score; activity mode forces max_retakes/passing_score to null).

        • 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 CardTypeModal selector (six selectable types remain).

        • Fixed the squished/overflowing asset grid in BackgroundSelectorModal (auto-rows-max with a scroll container).

        • Fixed POST /api/creator/create-activity rejecting valid payloads: optional Zod fields received null; the route now passes undefined for absent settings and normalizes activity_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 requires image_url for 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 (LearnerQuestionLayout now shows only the question number plus background/audio indicators).

        • Removed stale default card titles such as "New Quiz Card" from the learner intro (ActivityCardContent filters 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 / onEscapeKeyDown preventDefault) so editing is not lost on accidental outside clicks.

        • Fixed question-source tab switching wiping questions on the Activity Card editor (handleQuestionSourceChange no 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, ReorderContext epoch-keyed Monaco remount (fixes an InstantiationService crash), and asset grid scroll on the visual canvas. (Cross-referenced with the Visual Canvas internal technical guide.)

  5. Infrastructure & Operations

    • Dependencies:

      Dependency

      Notes

      Supabase

      Stores activities, questions, submissions, and quest content

      Supabase Auth

      User authentication and authorization (getCreatorAuthContext, authenticateUser) — replaces Clerk

      Zod

      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 Form

      React 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.ts and tests/e2e/creator/standalone-question-node.spec.ts exercise Question/Quiz nodes in the player, tests/unit/validate-quiz-submission.test.ts and tests/unit/forum-and-learner.schema.test.ts cover quiz-submission schema parsing (including image-map {x,y} payloads), and tests/creator/utils/canvas-import.test.ts covers 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 (gradeQuestion returns false for essay/reflection; the canvas gradeQuizQuestion path auto-passes an in-range essay by word count only).

        • The in-repo questions_type_check constraint lists five types and omits essay/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 skippedCount value in the update-questions response — 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


Was this article helpful?