Activity Cards

  1. Overview
  2. Internal Technical Guides
  3. Develop (Content Production)
  4. Activity Cards

  1. Front Matter

    • Title: Activity Cards

    • Author: Krizha Onise Cortez (armaminter)

    • Reviewers: Joylynne Grace Esportuno (teruterubozuuu), Jethro Lagmay (dyorgie), Sean Patrick Caintic (scorevi)

    • Created: January 2026

    • Status: Approved and Merged

    • References:

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

  • 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.

    • 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 Mode - Ungraded activity mode that allows unlimited attempts without storing quiz submissions.

      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.

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

  • Technologies Used:

    • Next.js App Router

    • React

    • TypeScript

    • Supabase

    • Clerk Authentication

    • React Hook Form

    • 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.

  1. Detailed Design & Implementation

  • Data Model / Schema:

  • 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

    • banner_color

    • banner_image_url

    • grading_settings

    • 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

    • image_url

    • background_image

    • background_audio

    • reflection_prompt

    • settings

  • Supported Activity Card types:

    • Multiple Choice

    • Checkbox

    • True / False

    • Identification

    • Essay

    • Image Map

  • 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

    • quest_id

    • type

    • content

    • motivation

    • order_index

  • Activity Card content stores:

    • activity_id

    • questionSource

    • questions

    • title

  • activity_submissions

    • Stores learner quiz attempts.

  • Relevant fields:

    • id

    • learner_id

    • activity_id

    • quest_id

    • content_card_id

    • answers

    • score

    • percentage

    • passed

    • submitted_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.

  • Relevant fields:

    • creator_id

    • file_name

    • file_url

    • asset_type

    • thumbnail_url

  • API Specification:

  • Activity Management APIs

    • GET /api/creator/quest-content-cards/list

      • Returns all activities owned by the authenticated creator.

    • POST /api/creator/create-activity

      • Creates a new Question Hub activity after validating activity settings and banner information.

    • GET /api/creator/get-activity

      • Retrieves an existing activity together with its configuration.

    • PUT /api/creator/update-activity

      • Updates an existing activity.

    • DELETE /api/creator/delete-activity

      • Deletes an activity together with its associated question cards.

  • Question Card APIs

    • GET /api/creator/list-question-cards

      • Retrieves every question belonging to an activity.

    • POST /api/creator/update-questions

      • Creates, updates, and removes Activity Cards within an activity.

    • PUT /api/creator/reorder-questions

      • Updates the ordering of Activity Cards after drag-and-drop operations.

  • Quest Activity Card APIs

    • GET /api/creator/quest-content-cards/list

      • Retrieves Activity Cards embedded inside a Quest.

    • POST /api/creator/quest-content-cards/create

      • Creates a new Activity Card inside the Form Editor.

    • PUT /api/creator/quest-content-cards/update

      • Updates an existing Activity Card.

    • DELETE /api/creator/quest-content-cards/delete

      • Removes an Activity Card from a Quest.

    • PUT /api/creator/quest-content-cards/reorder

      • Updates the ordering of Quest content cards.

    • POST /api/creator/convert-canvas-to-cards

      • Synchronizes Visual Canvas Quiz nodes into publishable Activity Cards.

  • Learner APIs

    • GET /api/learner/get-activity-questions

      • Retrieves activity questions and assessment settings for learners.

    • POST /api/learner/submit-activity-answers

      • Grades learner answers, stores quiz submissions when applicable, updates learner 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.

  • Asset Upload APIs

    • POST /api/creator/upload-assets

      • Uploads Image Map images and activity assets.

    • POST /api/creator/quest-content-cards/upload-media

      • Uploads media attached to Activity Cards.

  • Logic & Workflows:

  • Activity Creation Workflow

    1. Creator opens the Question Hub.

    2. Creator creates a new activity.

    3. Activity information is validated.

    4. Banner images are uploaded when provided.

    5. The activity is saved into the activities table.

    6. The Activity List refreshes automatically.

  • Question Card Management Workflow

    1. Creator opens an Activity.

    2. Existing Activity Cards are retrieved.

    3. Creator adds, edits, deletes, or reorders question cards.

    4. Client validates required fields based on card type.

    5. Updated cards are submitted through the Question Card API.

    6. The API validates ownership and question data.

    7. Questions are inserted, updated, or deleted from the database.

    8. Updated Activity Cards are returned to the editor.

  • Quest Activity Card Workflow

    1. Creator opens the Form Editor.

    2. Creator inserts an Activity Card.

    3. The card can reference an existing Question Hub activity or use custom questions.

    4. Activity configuration is synchronized into quest_content_cards.

    5. For linear quests, changes are synchronized to the Visual Canvas metadata.

    6. Published quests expose the Activity Card to learners.

  • Learner Activity Workflow

    1. Learner opens a published quest.

    2. Activity questions are retrieved.

    3. Activity settings determine question randomization, option randomization, timers, and grading behavior.

    4. Learner answers all questions.

    5. Submission is validated.

    6. The grading engine evaluates each answer.

    7. Quiz submissions are stored when applicable.

    8. Learner quest progress is updated.

    9. Results are displayed to the learner.

  • Visual Canvas Synchronization Workflow

    1. Activity Cards inside the Form Editor are represented as Quiz Nodes in the Visual Canvas.

    2. Custom questions and Question Hub references are synchronized between both editors.

    3. Canvas publishing converts Quiz Nodes into Quest Content Cards.

    4. Published quests use the synchronized content during learner execution.

  1. Infrastructure & Operations

  • Dependencies:

    Dependency

    Notes

    Supabase

    Stores activities, questions, submissions, and quest content

    Clerk Authentication

    User authentication and authorization

    React Hook Form

    Activity and question form management

    Zod

    Shared validation schemas

    React Dropzone

    User notifications

    Sonner Toast

    Success and error notifications

    Supabase Storage

    Activity banners and Image Map assets

    Visual Canvas

    Synchronizes Quiz Nodes with Activity Cards

  • 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 region validation

    • Quiz submission validation

    • Learner enrollment validation

    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

    • Known Limitations:

    • Reflection cards exist internally but cannot currently be added through the Question Hub interface.

    • Essay and Reflection responses require manual evaluation and are not automatically graded.

    • 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.

  • Maintenance & Support

    • Troubleshooting:

      • Activity cannot be created

        • Verify required fields are completed.

        • Verify activity title is valid.

        • Verify creator permissions.

        • Verify database connection.

      • Question cards cannot be saved

        • Verify all required question fields are completed.

        • Verify at least one correct answer exists.

        • Verify Image Map regions are properly configured.

        • Verify activity ownership.

      • 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.

    • 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.

Document version:

1.0 - Draft, Feature pushed to dev server after initial dev review, 03/03/2026

1.1 - Published, Initial internal technical guide for the Activity Card System, July 2026.

Written by kc Last updated July 3, 2026
Was this article helpful?