Mentor Persona

Author: Mich Tapawan → James Derick Billate
Reviewer:
Creation Date: July 2, 2026
Status: Approved and Merged
References: https://github.com/wyzlab/WyzQuests/issues/74

INTRODUCTION AND GOALS

Problem Summary: This feature allows the Creator to assign a particular image to gamify the overall quest, serving as motivation and companion of Learners as they progress with the quest content. Creators have the ability to choose pre-existing Sage, Warrior, or Healer mentor images, or customized mentor images.

Goals and Non-goals:

• Choose and assign mentors from pre-existing images embedded in the app.

• Upload or link specific images if Creators want a customized version of companions for Learners.

• Store the selected mentor image URL in the quest record through mentor_img_link.

• The mentor does not fully display yet in the Quest Player experience and should be validated separately in learner view.

• This feature does not define a dedicated mentor persona enum yet; it currently stores the selected image URL.

HIGH-LEVEL ARCHITECTURE

System Diagram:

Technologies Used:

Frontend: Next.js, React, Tailwind CSS, Shadcn Components, Next Image, Sonner toast.

Backend: RESTful API routes, TypeScript, Zod Validation, Clerk Authentication, agency ownership verification, Supabase.

Storage: Supabase Storage bucket public-assets.

Database: Supabase Postgres tables quests and asset_metadata.

DETAILED DESIGN & IMPLEMENTATION

This feature is connected to asset_metadata and quests, which are also used by 3.1 Asset Library and 1.1 Project Creation.

Primary quest field:

quests.mentor_img_link: Stores the selected mentor image URL. This may be a template image URL, externally linked image URL, or uploaded Supabase Storage public URL.

Related asset metadata fields for uploaded mentor images:

• creator_id

• file_name

• file_path

• file_url

• file_type

• file_size

• asset_type = "quest_mentor"

• usage_context = "quest:{quest_id}"

API Specification:

These APIs are updated with the inclusion of the mentor_img_link column in Supabase queries. They can be accessed only if the user is logged in as Creator or is authorized through agency-scoped ownership rules.

PATCH /api/creator/(content)/update-quest
Updates quest fields including mentor_img_link.

GET /api/creator/(content)/get-quest
Retrieves quest details including mentor_img_link.

POST /api/creator/upload-mentor-image
Uploads any customized mentor image from the Creator's local device. This is connected to Asset Library workflow for uploading images, but this API has mentor-specific validation, storage pathing, quest update behavior, and response messages.

Required Data: quest_id and file via FormData.

Upload path: public-assets/quests/{quest_id}/mentor.jpg

Core Logic and Workflow:

• Creator signs in.

• Creator chooses a quest from the dashboard.

• Creator opens the quest Overview page.

• Creator clicks Change Mentor or Select Mentor.

• MentorSelectionModal opens.

• Creator chooses one of three modes: Via Template, Via Link, or Upload Local.

• For Via Template, Creator selects one of the embedded templates: Elder Sage, Warrior Guide, or Mystic Healer.

• For Via Link, the image URL is validated client-side before submission.

• For Upload Local, file type and file size are validated before upload.

• If uploading locally, /api/creator/upload-mentor-image uploads the file, gets the public URL, updates quests.mentor_img_link, and inserts asset_metadata.

• If using template or link, the Overview page calls quest update with mentor_img_link.

• Quest Overview updates its UI preview and shows success toast.

Template Mentor Images:

• /images/creator/mentor_templates/mentor-sage.png

• /images/creator/mentor_templates/mentor-warrior.png

• /images/creator/mentor_templates/mentor-healer.png

INFRASTRUCTURE & OPERATIONS

Dependencies: No known major dependencies other than Zod validation to ensure data inputs and returns are correct and accurate. The feature depends on Quest Overview, Quest update/fetch APIs, Supabase Database, Supabase Storage, Asset Library metadata conventions, and agency ownership validation.

Monitoring & Alerting:

• No major monitoring is needed because most functionality is image selection, URL assignment, or file upload.

• Alert notification or logging should be used whenever internal services do not provide accurate returns or have an error.

• Monitor upload failures for /api/creator/upload-mentor-image.

• Monitor Supabase Storage failures for public-assets.

• Monitor failed quest updates where mentor_img_link cannot be saved.

Deployment Plan:

• Ensure that there is a migration or column under quests table named mentor_img_link.

• Ensure mentor_img_link is included in quest get and update API schemas/queries.

• Ensure UI/UX for changing the mentor is available via Overview.

• Ensure public-assets storage is configured for mentor image public URL access.

• Ensure asset_metadata.asset_type allows quest_mentor.

TESTING AND QUALITY ASSURANCE

Testing Strategy:

• Sign in as a Creator.

• Choose a particular quest via the dashboard.

• Open the quest Overview page.

• Click Change Mentor or Select Mentor.

• Choose Via Template.

• Select Sage, Warrior, or Healer.

• Ensure the quest mentor is updated in UI/UX and database record.

• Choose Via Link.

• Enter a valid image URL and confirm it updates mentor_img_link.

• Enter an invalid image URL and confirm validation blocks it.

• Choose Upload Local.

• Upload a valid image under 5MB and confirm it is stored in Supabase Storage.

• Confirm uploaded file URL is saved to quests.mentor_img_link.

• Confirm asset_metadata creates a quest_mentor record.

• Try uploading a non-image file and confirm 400 response.

• Try uploading an image larger than 5MB and confirm 400 response.

Known Limitations:

• There are no known major limitations for choosing, fetching, and assigning a mentor image to the quest.

• The mentor does not fully display yet in the Quest Player and should be validated separately before claiming learner-facing completion.

• There is no dedicated mentor persona enum yet for Sage, Warrior, or Healer; selection is stored as an image URL.

• Only one uploaded mentor file path is used per quest: quests/{quest_id}/mentor.jpg, with upload upsert behavior.

MAINTENANCE AND SUPPORT

Troubleshooting:

• Re-migrate the mentor_img_link column if it is missing from quests.

• Ensure all APIs related to quest creation and quest fetching include mentor_img_link in their Supabase queries where needed.

• Ensure all APIs related to quest updating allow mentor_img_link in their validation schema.

• Check Supabase Storage bucket public-assets if uploaded mentor images fail to load.

• Check file size and MIME type if upload fails with 400.

• Check quest ownership and agency resource ownership if upload fails with 404 or access denied.

• Check asset_metadata insert failures separately; the upload may still succeed even if metadata tracking fails.

Document Version

1.0 - Documentation draft, feature is merged, 07/02/2026

1.1 - Enhanced documentation of Mentor Persona, 07/10/2026

1.2 - Minor document enhancements, 07/14/2026