Activity Cards

Feature Owner: Krizha Onise T. Cortez
Updated by: Patrick Babala
Module: Develop
Priority: P0
Status: Updated and Published (v2.0)
Date: July 2026 (last updated September 30, 2026)

Product-facing companion to the Internal Technical Guide — Activity Cards (Revision 2.0). This document covers user flows, information architecture, rules, QA, open questions, dependencies, and ownership; deep engineering detail (schema, API specs, grading internals, troubleshooting) lives in the technical guide.

Executive Summary

What is this feature?

Activity Cards allow creators to build reusable assessments through the Question Hub and embed them into quests using the Form Editor and Visual Canvas. Learners complete these activities during quests and receive graded results based on the configured settings.

Why does it matter?

Reusable activities reduce duplicate work while providing consistent quizzes and assessments across multiple quests.

What's the MVP scope?

  • Create Question Hub activities

  • Create question cards

  • Embed activities into quests

  • Learner quiz runtime

  • Automatic grading

  • Quiz submissions

What changed in Revision 2.0?

  • The learner activity card was de-cluttered: question type pills/labels and stale default titles (e.g. "New Quiz Card") no longer appear.

  • Reflection was removed from the Question Hub card-type selector, so creators now choose from six types: Multiple Choice, Checkbox, True/False, Identification, Essay, Image Map.

  • Authoring is less error-prone: the Add Question modal and card-type selector no longer close on accidental outside clicks, and switching between Custom and Hub question sources no longer wipes in-progress questions.

  • Code blocks in cards gained a Templates picker, and the Form Editor card preview now renders each card type correctly.

  • Bug fixes: activity creation via the Question Hub, the asset/banner picker layout, and Image Map question saving.

1. USER PAIN POINT & SOLUTION

Without Activity Cards

Creators had no centralized way to create reusable assessments and had to manually recreate questions across multiple quests.

Pain Point

  • Emotional

    • Creating quizzes repeatedly becomes tedious and difficult to maintain.

  • Functional

    • Questions cannot easily be reused or updated across quests.

  • Business Impact

    • Course creation takes longer and assessment consistency decreases.

Current State

Creators build reusable activities in Question Hub and attach them to quests. Learners complete activities directly inside quests with automatic grading and progress tracking.

2. 4D FRAMEWORK MAPPING

  • Diagnose — Identify learner understanding through graded assessments and quiz attempts.

  • Design — Create reusable question sets and configure assessment behavior.

  • Develop — Manage question content, grading rules, randomization settings, and learner submissions.

  • Deliver — Present activities inside quests and record learner performance.

3. USER FLOWS

Entry Point

  • Creator

    /creator/question-hub
    /activity/[id]
  • Quest Editor

    Form Editor → Activity Card
  • Learner

    Quest Player → Activity Card

Success Criteria

  • Activity successfully created.

  • Questions saved.

  • Activity attached to quest.

  • Learner completes activity.

  • Quiz is graded successfully.

  • Progress updates correctly.

Main Flow

  • Creator opens Question Hub.

  • Creates a new activity.

  • Adds question cards.

  • Configures activity settings.

  • Saves the activity.

  • Selects the activity inside the Form Editor.

  • Publishes the quest.

  • Learner opens the quest.

  • Learner answers questions.

  • Activity is graded automatically.

  • Results and learner progress are displayed.

Edge Cases

  • No Question — Prevent activity from being saved.

  • Invalid Activity — Display validation errors.

  • API failure — Display save or load failure.

  • Quiz retake limit reached — Prevent another submission.

  • Activity Mode — Display results without storing quiz submissions.

  • Incomplete question card — The question is skipped on save rather than blocking the whole activity; the editor reports how many were skipped. (Revision 2.0)

  • Accidental outside click — The Add Question and card-type modals stay open. (Revision 2.0)

  • Question source switched — Switching between Custom and Hub preserves in-progress questions. (Revision 2.0)

Decision Points

  • If Question Hub Activity — Reuse stored questions.

  • else — Use custom questions stored directly in the quest.

4. INFORMATION ARCHITECTURE

Primary Information

  • Activities

  • Questions

  • Activity Settings

  • Quiz Results

Secondary Information

  • Timer

  • Passing Score

  • Retake Count

  • Randomization Settings

Tertiary Information

  • Banner Image

  • Background Assets

  • Activity Description

Action

  • Primary CTA

    • Save Activity

    • Submit Activity

  • Secondary Actions

    • Add Question

    • Edit Question

    • Delete Question

    • Reorder Questions

    • Configure Settings

5. WIREFRAMES

Excluded — Feature fully implemented.

6. WIREFLOWS

Excluded — Feature fully implemented.

7. PROTOTYPE

Excluded — Feature fully implemented.

8. BACKEND SCHEMA

Database tables

  • activities — Stores reusable activity metadata including title, description, activity type, grading configuration, timer, retake settings, and banner assets.

  • questions — Stores all question cards belonging to an activity including question type, answers, options, image map regions, and settings.

  • quest_content_cards — Stores Activity Cards embedded inside quests.

  • activity_submissions — Stores learner quiz submissions, scores, feedback, attempts, and completion status.

  • quest_enrollments — Stores learner progress updates after completing activities.

  • asset_metadata — Stores uploaded banner images and other activity assets.

(Column-level detail, constraints, and the essay/reflection type-constraint caveat are in the Internal Technical Guide — Activity Cards, "Data Model / Schema".)

9. API ENDPOINTS

Activity Management

  • GET /api/creator/list-activities

  • POST /api/creator/create-activity

  • GET /api/creator/get-activity

  • PUT /api/creator/update-activity

  • DELETE /api/creator/delete-activity

Question Cards

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

  • POST /api/creator/update-questions

  • PUT /api/creator/reorder-questions

Quest Integration

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

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

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

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

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

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

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

  • POST /api/creator/quest-content-nodes/get-upload-url

  • DELETE /api/creator/quest-content-nodes/delete-media

Learner

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

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

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

  • GET /api/learner/get-retake-status

  • GET /api/learner/quest-content-cards

Removed

  • POST /api/creator/quest-content-cards/upload-media — replaced by the signed-URL upload flow (quest-content-nodes/get-upload-url, quest-content-cards/upload-motivation-media). (Revision 2.0)

10. DATA REQUIREMENTS

Frontend Needs

  • Activity ID

  • Activity metadata

  • Question list

  • Question order

  • Activity settings

  • Quiz configuration

  • Learner answers

  • Submission results

  • Progress state

API Calls, Frontend Will Make

  • Load activities.

  • Load activity questions.

  • Save activities.

  • Save question cards.

  • Reorder questions.

  • Submit learner answers.

  • Retrieve learner submissions.

  • Retrieve retake status.

11. PERFORMANCE CONSIDERATIONS

Database Optimization

Question cards are normalized into separate database tables, allowing activities to be reused without duplicating question content.

Only learner submissions are stored for quiz-mode activities, reducing unnecessary database writes for practice activities.

12. SECURITY & AUTHORIZATION

Who Can Access This Feature?

Creator

Full CRUD access to owned activities.

Reviewer

Read-only access through quest review flows.

Learner

Can only access activities attached to published quests in which they are enrolled.

13. ERROR HANDLING

Current Existing Error Handling

  • Missing activity IDs return validation errors.

  • Ownership is verified before updates.

  • Invalid activity settings are rejected.

  • Incomplete question cards are filtered (skipped) before saving and reported as a skipped count. (Revision 2.0)

  • Quiz submission validates enrollment and retake limits.

  • Invalid question data returns descriptive validation errors.

  • API failures return appropriate error responses without corrupting saved activities.

  • Image Map region geometry is validated in the editor before save (the server accepts the card once its image is present). (Revision 2.0)

14. TESTING CHECKLIST

Happy Path

  • Create activity.

  • Edit activity.

  • Delete activity.

  • Add question cards.

  • Save questions.

  • Reorder questions.

  • Configure quiz settings.

  • Embed activity into a quest.

  • Complete learner activity.

  • Grade learner submission.

Edge Cases

  • Empty activity.

  • Invalid question.

  • Quiz retake exceeded.

  • Timer expiration.

  • Activity mode versus Quiz mode.

  • Failed API requests.

  • Unauthorized access.

Revision 2.0 Regressions

  • Question Hub card-type selector no longer offers Reflection.

  • Asset/banner picker grid is not squished or overflowing.

  • Create-activity succeeds for both Activity and Quiz modes (no spurious validation error).

  • Image Map question with regions saves and reappears after reload.

  • Learner cards show no type pills/labels and no default titles.

  • Add Question / card-type modal does not close on outside click.

  • Switching Custom ⇄ Hub question source preserves questions.

  • Codeblock card Templates picker inserts a template.

  • Form Editor card preview renders for codeblock/video/image/audio/file/link/reflection/discussion/question cards.

  • Canvas node triple-dot menu opens and its actions work.

15. OPEN QUESTIONS

  • Should Reflection become an official Question Hub card type? — Resolved (Revision 2.0): No. Reflection was removed from the Question Hub card-type selector; creators choose from six types. Reflection remains available only internally / in existing cards. Revisit if a dedicated reflection workflow is prioritized.

  • Should manual grading for Essay questions be supported? — Still open. Essay responses are not auto-graded in the Question Hub path.

  • Should Activity Cards support additional assessment types beyond the current six question types? — Still open. Note: confirm the live questions_type_check constraint before adding Essay/Reflection as first-class types (see technical guide).

  • Should randomization behavior become configurable per question instead of per activity? — Still open.

16. OUT OF SCOPE

  • Real-time collaborative activity editing.

  • Manual grading workflow.

  • SCORM/xAPI assessment exports.

  • Push notifications for completed quizzes.

  • Advanced analytics beyond current submission tracking.

17. SUCCESS METRICS

  • Activity creation success rate.

  • Question save success rate.

  • Quiz submission success rate.

  • Learner completion rate.

  • Average quiz completion time.

  • API error rate.

  • Assessment reuse across multiple quests.

18. DEPENDENCIES

This feature depends on

  • Question Hub

  • Quest Editor

  • Form Editor

  • Visual Canvas

  • Quest Content Cards

  • Supabase Storage

  • Authentication

  • Learner Quest Player

These features depend on this

  • Form Editor Activity Card

  • Visual Canvas Quiz Node

  • Quest Publishing

  • Learner Quest Player

  • Quest Progress Tracking

  • AI-generated Activity Suggestions

19. TIMELINE & OWNERSHIP

  • Sprint: Feature implemented and deployed.

  • Backend: Krizha Onise Cortez

  • Frontend: Krizha Onise Cortez

  • Estimated Completion: Feature completed.

  • Revision 2.0 (September 2026): Engineering overhaul by Patrick Babala — PRs #682, #701, #708. Question Hub bug fixes, learner card refinement, modal/tab-switch/template/preview fixes. Product detail unchanged for the end learner aside from the UI clean-ups above.

Document Version

2.0 — Published, Revision 2.0: added product-facing changes (card-type selector, learner card clean-up, authoring fixes), Revision 2.0 regressions to QA, resolved the Reflection open question, corrected the API endpoint list (added reorder/node upload routes; marked upload-media removed), refreshed ownership. Updated by Patrick Babala, 09/30/2026.

1.0 — Initial hand-off documentation for the Activity Card System, July 2026.


Was this article helpful?