Author: James Derick Billate
Reviewer: Jethro Lagmay & Sean Patrick Caintic
Creation Date: June 29, 2026
Status: Approved and Merged
References: https://github.com/wyzlab/WyzQuests/issues/49
INTRODUCTION AND GOALS
Problem Summary: Allows a particular creator of an Agency to check out its users, may it be Learners, Creators and Reviewers with their current statuses and states. Offering basic analytics to provide better decision making with the workflow or content.
Goals & Non-Goals: The current state of the feature only allows the following per role:
Learners: Number of Learners and Enrollments, List of Learners, Basic Learner Progress and Completion Rate
Creators: Number of Creators, List of Creators, Number of Content Created and Content Statuses
Reviewers: Number of Reviewers, List of Reviewers and Review Statuses
Agency Admin also has the ability to export the list and minor analytics in their local divides. However, there’s no further implementation especially with login states or behavior for all users.
HIGH-LEVEL ARCHITECTURE
System Diagram:
Technologies Used: Next.js, Tailwind CSS, Zod Validation, Supabase, RESTful APIs, Shadcn Components
DETAILED DESIGN & IMPLEMENTATION
Schema: Connected to [5.2] Agency Admin View
API Specification:
All listed APIs for this feature must (1) An account linked to as Agency Admin to an Agency and (2) Authenticated via the Agency Admin Account. Other accounts will not have access to either UI or APIs under this feature
GET /api/agency/learners
Fetches all the learners enrolled to a quest created by the Agency Creators.
API Returns:
Status | Message |
404 | Agency not found |
500 | “Failed to fetch members” with dynamic error.message |
200 OK | agency, learners and currentUserClerkId (the metadata of the agency, list of learners) |
GET /api/agency/team/list
Fetches all the members of the Agency combined, Creators and Reviewers. Additionally, content created or reviewed by the members
API Returns:
Status | Message |
404 | Agency not found |
500 | “Failed to fetch members” with dynamic error.message |
200 OK | agency, members, quests and currentUserClerkId (the metadata of the agency, list of members and quests) |
PATCH /api/agency/team/members/[memberId]
Updates a member in an agency.
API Returns:
Status | Message |
403 (non-owner) | “Only agency owners can change team member roles” |
400 (validation) | "Invalid request body" with dynamic parsed.error.flatten().fieldErrors |
404 | "Member not found" |
403 (deleting non-agency member) | "Member does not belong to your agency" |
500 | "Failed to update member role" with dynamic error.message |
200 OK | “${member.invited_email} role updated to ${newRole}” |
DELETE /api/agency/team/members/[memberId]
Removes a member in an agency.
API Returns:
Status | Message |
403 (non-owner) | “Only agency owners can remove team members” |
404 | "Member not found |
403 (deleting non-agency member) | "Member does not belong to your agency" |
500 | "Failed to remove member” with dynamic error.message |
200 OK | “${member.invited_email} removed from agency” |
Core Logic & Workflow:
Sign-in as an Agency Admin to navigate Agency Dashboard
Traverse through the unified sidebar and click either Learners or Team
Team: Await, system validates if you are an Agency Owner and fetches the learners enrolled and or progress through content generated within an agency.
Team: Await, system validates if you are an Agency Owner and fetches the members with their content and status.
If you choose to update, click the dropdown and choose the approriate option to change.
If you choose to DELETE, click the trash bin icon
fetchAgencyQuest(creatorIds: string[]) - is an helper function to GET /api/agency/team/list/route.ts which validates a quest if it is created under an account which is a member of the agency
fetchLearners(agencyQuests: { id: string }[]) - is an helper function to GET /api/agency/learners/route.ts which assure that the fetch learner is connected to a quest generated within an agency.
INFRASTRUCTURE & OPERATIONS
Dependencies: No known major dependencies other than ZOD validation to ensure data inputs and returns are correct and accurate
Monitoring & Alerting: No major monitoring is needed, since most of the functionalities in this feature are data display purposes only. Alert notification thus will be sent whenever internal services do not provide accurate returns or have an error.
Deployment Plan:
Ensure that necessary APIs are configured to an Agency and are restricted to Agency Owner.
Ensure that the buttons can be navigated easily and accurately route to correct data displays.
Necessary tables such as agency_members, app_users and quest_enrollments are available via Supabase.
TESTING & QUALITY ASSURANCE
Testing Strategy:
List of learners with specified numerical analytics are accurate
List of members with specified numerical analytics are accurate
Changing of roles to members reflect both via UI and database
Deletion of members reflect both via UI and database
Exporting data via Export Data button with applicable .csv file being downloaded
Known Limitations:
Not tracking of logins across users within an agency
MAINTENANCE & SUPPORT
Troubleshooting:
Via Admin dashboard, create and assign accounts to an Agency
Generate content via an Agency Creator to check enrolled learners accurately.
Document Version
1.0 - Draft, Feature pushed but in need for further development 06/29/2026
