Manage Folder Permissions & Sharing | WyzQuests Documentation

Feature Owner: James Derick Billate
Module: Organization
Priority: Must
Date: July 7 2026

Executive Summary

What is this feature?

Manage Folder Permissions allows Creators and Agency Admins to share their folders with other WyzQuests accounts. It gives folder owners and permitted collaborators a way to assign access levels to project, quest, and adventure folders so content can be viewed, edited, or administered without requiring the owner to manually share content from their own device.

Why does it matter?

Without folder permissions and sharing, other accounts cannot access content owned by a Creator or Agency Admin. This limits content reviews, viewing, and collaboration across WyzQuests. Folder Permissions makes folder access more dynamic by allowing selected users to collaborate within organized content spaces.

What's the MVP scope?

Permission invite.
Permission CRUD process.
Permission levels: view, edit, admin, and owner.
Permission logic for folder access.
Folder permission support for project, quest, and adventure folders.

1. User Pain Point & Solution

John created an Agency Admin workspace, invited creators, and created a specified folder. However, he needs to share that folder with others remotely instead of giving access from his own device or manually transferring content. Manage Folder Permissions lets John invite accounts by email and grant the right permission level directly from the Content Library.

Pain Points

Emotional: Tired and exhausted from manual sharing and repeated coordination.
Functional: Remote users cannot access needed folder content unless the owner manually shares it or exposes content another way.
Business: More accounts can efficiently access folders and their content, improving agency workflow and content collaboration.

2. 4D Framework Mapping

Diagnose: Provides another way to check which accounts or users can access content under specific folder permissions.

Design: Generates an overview of shared content and who has permission to access it.

Develop: Further enhances the workflow and organization of team dynamics through folder-based collaboration.

Deliver: Provides more ways to deliver quality output by ensuring content is organized and accessible per folder.

3. USER FLOWS

Entry Points: Agency Admin or Creator logs in and opens Content Library through Library navigation.

Success Criteria: Agency Admin or Creator can open a folder's Permissions modal, add a user by email, assign a permission level, update that permission, and revoke access.

Main Path (Happy Path)

Sign in as an Agency Admin or Creator.
Click Library or Content Library.
Navigate the dashboard.
Create or select a folder.
Open the folder kebab menu.
Click Permissions.
Input the invited user's email.
Select permission level: view, edit, or admin.
Click Share.
System validates folder access and user existence.
System saves the permission and sends an email notification.

No Data: Alert the Agency Admin or Creator that the folder, account, or permission does not exist.

API Error: Terminate the permission process promptly and display the proper error codes and messages.

Permission Denied: Do not fetch or modify folders and permissions when the user is not permitted.

Decision Points:

IF folder exists THEN allow CRUD of folder permissions ELSE halt CRUD of folder permissions.
IF invited email belongs to a WyzQuests account THEN add permission ELSE show user not found.
IF requester has owner, admin, or edit permission THEN allow permission changes ELSE deny request.
IF permission already exists THEN show conflict message ELSE create permission.
IF permission is revoked THEN remove access ELSE keep current permission.

4. Information Architecture

Primary Information

Agency or Creator information.
Folder information.
Invited account information.
Permission level information.

Secondary Information

Folder type: project, quest, or adventure.
Folder name.
User email.
User name.
Current permission member list.

Tertiary Information

Email notification status.
Permission timestamps.
Owner permission marker.

Actions

Primary CTA
- “Permissions”
Secondary Actions
- "Permissions" -> "Add"
- "Share"
- "Change Permission"
- "Revoke Permission"
- "Done"

5. Data Requirements

Frontend Needs

Agency or Creator information.
Folder ID.
Folder type.
Invited account email.
Permission level.
Existing folder permission list.
User name and email for permission display.

API Calls Frontend Will Make

GET /api/folder/permissions/{folder_id}
POST /api/folder/permissions/{folder_id}
PATCH /api/folder/permissions/{folder_id}
DELETE /api/folder/permissions/{folder_id}

6. Performance Considerations

Database Optimization

Ensure necessary Supabase queries are limited to needed columns rather than global fetching.
Use indexes on folder_permissions.folder_id and folder_permissions.user_id.
Use a unique constraint on folder_id and user_id to avoid duplicate permissions.
Validate folder ownership before running unnecessary permission mutation work.
Clean up permission rows when folders are deleted.

7. Security & Authorization

Who Can Access This Feature?

Administrator: No access.
Reviewer: No access.
Creator: Full access.
Learner: No access.
Agency Admin: Full access.

8. Error Handling

Current Existing Error Handling

Current Existing Error Handling
Invalid credentials -> authentication error.
Expired verification tokens -> rejected.
Previously consumed tokens -> rejected.
Invalid verification requests -> schema validation error.
Unauthorized users -> cannot request permission operations.
Failed folders or permissions -> error response.
Non-existent account -> user not found error.
Existing permission -> conflict error.
Permission not updated -> internal error.
Permission not revoked -> internal error.

9. Testing Checklist

Happy Path

Sign in as an Agency Admin or Creator.
Navigate to Library or Content Library.
Create a folder.
Open the folder kebab menu.
Click Permissions.
Add a user email.
Select view permission.
Confirm the user appears in the Members list.
Change permission to edit.
Change permission to admin.
Revoke the permission.
Confirm revoked user is removed from the list.

Edge Cases

Unauthorized account.
Folder not found.
Permission not found.
User account not found.
Duplicate permission invite.
Requester only has view access.
Invalid email input.
Invalid permission level.
Folder was deleted after modal opened.
Email notification fails after permission is added.

10. OPEN QUESTIONS

Should there be an ability for Agency Admins to organize quests or other content inside the folder?
Should Creators allow Reviewers to also have access to their folders?
Should parent folder permissions automatically apply to child folders?
Should edit permission allow permission management, or should permission management be admin-only?
Should folder sharing support pending invites for emails that do not yet have WyzQuests accounts?

11. OUT OF SCOPE

Permission level inheritance of parent -> child.
Deeper permission level logic for view and edit beyond current CRUD validation.
Pending invitation workflow for non-existing users.
Bulk folder sharing.
Public folder sharing.
Cross-organization sharing.

12. SUCCESS METRICS

List of all user accounts with specified permission level.
Creator or Agency Admin can add folder permissions.
Creator or Agency Admin can update folder permissions.
Creator or Agency Admin can revoke folder permissions.
Unauthorized users cannot manage folder permissions.

18. DEPENDENCIES

This feature depends on

Clerk Authentication.
Agency Admin, Creator, and User Account details.
Supabase Database.
Project Folders.
Quest Folders.
Adventure Folders.
Email Service.

This feature depends on this

Agency Creation.
Content Library.
Folder Creation.
Folder Navigation.
Folder Permission Email Notification.

19. TIMELINE & OWNERSHIP

Backend: James Derick Billate

Frontend: James Derick Billate

QA: Internal development testing

Estimated Completion: Feature completed.

Note: API Endpoints and Schema please refer to its Technical Documentation