Motivation Pop-ups

Author: James Derick Billate
Reviewer:
Creation Date: March 3, 2026
Status: Draft
References: https://github.com/wyzlab/WyzQuests/issues/36

INTRODUCTION & GOALS

Problem Summary: This feature allows the creators to generate custom motivational messages or images to increase learner’s interactivity while they are enrolled on a certain quest. Increasing stimulus to success and perseverance of learners while quest progress to become challenging and complex.

Goals & Non-Goals: The creator has the ability to customize motivation pop-ups to every card (e.g. text, question). They can upload limited to videos, gifs, audio and images. However, creators will not be able to access this feature if the disabled “Motivational Popup” in quest setting.

HIGH-LEVEL ARCHITECTURE

System Diagram:

Technologies Used: Clerk Authentication, Typescript, Next.js, Postgres (Supabase) and Tailwind CSS

DETAILED DESIGN & IMPLEMENTATION

Schema:

CREATE TABLE public.quests (
  id uuid NOT NULL DEFAULT gen_random_uuid(),
  created_at timestamp with time zone NOT NULL DEFAULT now(),
  creator_id uuid NOT NULL,
  adventure_id uuid,
  title text NOT NULL UNIQUE,
  introduction text NOT NULL,
  description text,
  updated_at timestamp with time zone NOT NULL,
  profile_img_url text,
  publishing_status text NOT NULL DEFAULT 'draft'::text CHECK (publishing_status = ANY (ARRAY['published'::text, 'draft'::text, 'archived'::text, 'submitted'::text, 'in_review'::text, 'changes_requested'::text, 'approved'::text])),
  accessibility_status text NOT NULL DEFAULT 'restricted'::text,
  tags ARRAY DEFAULT '{}'::text[],
  enrollment_count bigint NOT NULL DEFAULT '0'::bigint,
  is_count_visible boolean NOT NULL DEFAULT true,
  enrollment_limit bigint,
  motivational_popup boolean NOT NULL DEFAULT false,
  enrollment_fee bigint NOT NULL DEFAULT '0'::bigint,
  duration bigint,
  background_img_url text,
  background_audio_url text,
  mentor_img_link text,
  canvas_metadata jsonb NOT NULL DEFAULT '{"edges": [], "nodes": []}'::jsonb CHECK (canvas_metadata IS NOT NULL AND canvas_metadata ? 'nodes'::text AND canvas_metadata ? 'edges'::text AND jsonb_typeof(canvas_metadata -> 'nodes'::text) = 'array'::text AND jsonb_typeof(canvas_metadata -> 'edges'::text) = 'array'::text),
  skills ARRAY DEFAULT '{}'::text[],
  CONSTRAINT quests_pkey PRIMARY KEY (id),
  CONSTRAINT quests_creator_user_id_fkey FOREIGN KEY (creator_id) REFERENCES public.app_users(id),
  CONSTRAINT quests_adventure_id_fkey FOREIGN KEY (adventure_id) REFERENCES public.adventures(id)
);
 
CREATE TABLE public.quest_content_cards (
  id uuid NOT NULL DEFAULT gen_random_uuid(),
  created_at timestamp with time zone NOT NULL DEFAULT now(),
  updated_at timestamp with time zone NOT NULL DEFAULT now(),
  quest_id uuid NOT NULL,
  order_index integer NOT NULL,
  content jsonb NOT NULL DEFAULT '{}'::jsonb,
  type text NOT NULL,
  motivation jsonb DEFAULT '{}'::jsonb,
  CONSTRAINT quest_content_cards_pkey PRIMARY KEY (id),
  CONSTRAINT quest_content_cards_quest_id_fkey FOREIGN KEY (quest_id) REFERENCES public.quests(id)
);

Data Model

API Specification:

POST /api/creator/create-quest
For Creator to create custom quest

GET /api/creator/get-quest?quest_id=${questID}
For Creator to view the requested creation of a quest

PATCH /api/creator/update-quest
Whenever the Creator updates information of the quest

POST /api/creator/quest-content-cards/create
For Creator to create individual content card for the quest

POST /api/creator/quest-content-cards/upload-motivation-media
Whenever the Creator adds a motivation media (e.g. image, videos)

Logic & Workflows: To be updated, no prior documentation regarding this matter, necessary additions will be indicated during the testing process.

INFRASTRUCTURE & OPERATIONS

Dependencies:

The motivational pop-ups can only be accessed and created once the Creator have initiated a creation of quests and its content, thus the following features are dependencies of [3.5] Motivational Pop-ups:

• [1.7] Quest Creation

• [3.3] Activity Cards

Monitoring & Alerting: To be indicated after further testing. No prior documentation regarding this matter

Deployment Plan:

1. Ensure that necessary migration files are migrated safely in Supabase. Where necessary fields indicating motivational pop-ups’ field.

2. Ensure call-to-actions (CTA) are working properly, where navigation to the feature is accessible.

3. After which, deployment will be safely transmitted to production.

TESTING & QUALITY ASSURANCE

Testing Strategy:

1. Ensure that motivational pop-ups has its designated column under quest table. This is where the decision of adding a motivational pop-up on quest will be stored. Value indicate must be true or false.

2. Ensure that motivational pop-ups has also a designated column under quest_content_cards that only accepts json formatted data. This is where the motivation messages and media will be stored whenever displayed.

3. Necessary buttons that will help the creators navigate this feature.

4. That motivation pop-ups will be displayed on Learner’s screen on designated content cards.

Known Limitations: There are no known edge cases whatsoever have be documented throughout the testing process. Nonetheless, if such case will be determined, changes to this document will be applied.

MAINTENANCE & SUPPORT

Troubleshooting:

1. For in case, in media uploading (e.g. image, video, gif or audio), if the system does not accept the file. Check first the ZOD validation regex expression. Nonetheless, re-check the file type if it commits to the acceptable file formats.

2. For in case, text or media content will not be accepted by the system, reload the site. If its local, run npm run dev again. This is to possibly referesh API endpoints. Nonetheless, call or message a support to modify changes with the API.

3. For in case, the motivational pop-ups are not stored, either create a new column under quest_content_cards and quest tables, or remigrate existing migration files with these tables.

Changelog: No prior historical record were documented, neither in Github or via workspace. If such evidence arise during the testing process, necessary additions to this document must be indicated.

Document version: 1.0 - Draft, Feature already exists on dev server before and after initial dev review, 03/04/2026