Activity Cards

Feature Owner: Krizha Onise T. Cortez
Module: Develop
Priority: P0
Date: July 2026

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

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

Question Builder

/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

1. Creator opens Question Hub.

2. Creates a new activity.

3. Adds question cards.

4. Configures activity settings.

5. Saves the activity.

6. Selects the activity inside the Form Editor.

7. Publishes the quest.

8. Learner opens the quest.

9. Learner answers questions.

10. Activity is graded automatically.

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

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.

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

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

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

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.

• Unsupported question configurations are filtered before saving.

• Quiz submission validates enrollment and retake limits.

• Invalid question data returns descriptive validation errors.

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

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.
  

15. OPEN QUESTIONS

• Should Reflection become an official Question Hub card type?

• Should manual grading for Essay questions be supported?

• Should Activity Cards support additional assessment types beyond the current six question types?

• Should randomization behavior become configurable per question instead of per activity?
  

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.