Author: James Derick Billate — original author (Creation Date: March 27, 2026)
Updated by: Patrick Babala
Reviewers: Clyde Ador (@clydetims), Christian Denzon (@cdnzn), Cole (@ybcole) — review of the update PRs
Creation Date: March 27, 2026
Last Updated: 2026-10-01
Status: Published (revision 2.0)
References:
• Issue #77 — [5.3] Creator Hub (closed 2026-08-27)
• Sub-issue #661 — [5.3.1] Creator View Mode (closed 2026-08-19)
• Sub-issue #662 — [5.3.2] Creator Hub Search Functionality (closed 2026-08-19)
• PRs covered: #759 (search + view mode), #767 (status filter fix), #690 (thumbnail ratio, scroll, cache-busting), #780 (typed-confirm destructive modal)
• Dependencies: #70 — [1.1] Project Creation; #71 — [2.1] Form Editor
INTRODUCTION & GOALS
Problem Summary:
The Creator Hub is the creator-facing dashboard that lists all projects a creator owns (quests and adventures) and surfaces high-level activity metrics, learner-group analytics, recent activity, and an AI suggestion rail. The original v1.0 scope covered only display: "view the list or cards of their projects." It has since grown into the primary content-management surface for creators, including search, filtering, view modes, bulk selection, and the full archive → restore → permanent-delete lifecycle.
Goals & Non-Goals:
Goals (current):
Show creators an easy, efficient way to view and access their quests and adventures without querying the database.
Provide at-a-glance metrics: total quests, published quests, drafts, and adventures (
GET /api/creator/analytics).Support real-time search across title, introduction, tags, and skills (Issue #662, PR #759).
Support grid and list view modes with a persisted per-device preference (Issue #661, PR #759).
Filter by publishing status and by skills, and sort the Archive tab.
Support bulk selection with shift-click ranges, select-all, bulk archive, bulk restore, and bulk permanent delete.
Provide an Archive tab with a 120-day retention countdown, restore, and typed-confirmation permanent delete (PR #780).
Scope all lists and mutations by creator ownership, with agency and folder-permission overrides.
Non-Goals (unchanged in spirit, kept explicit):
No folder organization is performed from the dashboard itself; folder management lives in the Content Library / folder features (see issue #427 series).
Learner progress/authoring detail is out of scope for this dashboard except the
LearnerGroupAnalyticssummary widget.The review workflow (
submitted/in_review/changes_requested/approved) is owned by the quest review feature; the dashboard only reflects status and uses the review-lock polling endpoint.
Resolved items:
Original "Logic & Workflows: To be updated" — resolved. Workflows are documented under DETAILED DESIGN & IMPLEMENTATION → Logic & Workflows.
Original "Monitoring & Alerting: to be indicated after testing" — resolved. See INFRASTRUCTURE & OPERATIONS → Monitoring & Alerting.
Original known-limitations "no known edge cases" — resolved. Enumerated under TESTING & QUALITY ASSURANCE → Known Limitations.
HIGH-LEVEL ARCHITECTURE
System Diagram:
Technologies Used:
TypeScript, Next.js (App Router) route handlers and client components
Supabase — PostgreSQL (data), Storage (
public-assetsbucket), Supabase Auth (authentication)Correction: the original guide listed "Clerk Authentication". The platform migrated to Supabase Auth. The
app_users.clerk_idcolumn name is retained for legacy compatibility and stores the Supabase user id.
Tailwind CSS for styling; Radix UI primitives (
DropdownMenu,Popover,Tooltip) for menus/filtersZod for request validation;
ApiResponseHelperfor the standardized API envelopednd-kit for content drag-and-drop (folder views; card component is shared)
Sonner for toasts; Lucide icons
Playwright for end-to-end tests
Architecture notes:
Route guard.
app/creator/layout.tsxcallsauthenticateAnyRole(["CREATOR", "ADMIN"])and applies the View-As redirect before renderingCreatorLayoutClient, which provides theUnifiedSidebar,Header,CreatorContext, andBrandingProvider.Dashboard composition.
app/creator/page.tsxis a client component laid out asgrid xl:grid-cols-7: a 5-column main column (CreatorHeader,CreatorAnalyticCards,LearnerGroupAnalytics,MyContent) and a 2-column right rail (RecentActivity,AISuggestion).ModalCreateis mounted here as an overlay driven byCreatorContext.isModalActive.API layer. All creator APIs live under
app/api/creator/*. Every handler first callsgetCreatorAuthContext(), then appliesagencyResourceFilter(authContext)(.or(...)) so a creator sees their own content plus content owned by users in their agency, per the caller's role. Mutations additionally runverifyAgencyResourceOwnershipper item and fall back tocanManageItemsInFoldersfor folder administrators.Response envelope. All endpoints return the
ApiResponseHelpershape; clients readdata?.data ?? datafor forward compatibility.
DETAILED DESIGN & IMPLEMENTATION
Frontend components:
Component | File | Responsibility |
|---|---|---|
|
| Dashboard grid, View-As overlay, |
|
| Sidebar/header shell, |
|
| Title, Create Content, AI Assistant actions; opens |
|
| Four metric cards from |
|
| Learner-group summary widget |
|
| Tabs, search, filters, view mode, selection, bulk actions, data loading |
|
| Grid card: cover, badges, tags, folder badge, archive/delete/edit |
|
| List-view row (PR #759): thumbnail, tags, created/updated dates, actions |
|
| Archive tab: countdown, restore, permanent delete, bulk restore/delete |
|
| Floating bulk-action bar (select all / deselect / archive / restore / delete) |
|
| Reusable typed-confirmation modal (PR #780) |
|
| Archive sort field/direction |
|
| Extracts unique skills and applies OR filtering (W1.3) |
MyContent state model:
shownContent:"quests" | "adventures" | "archive"— tabs. The third tab is labeled Archive (TrashContentrenders it; the component keeps its historical name). The older "Trash" label in v1.0 docs is stale.statusFilter:"all" | "draft" | "published" | "submitted" | "in_review" | "changes_requested" | "approved".searchQuery,viewMode("grid" | "list"),selectedIds(selection mode is derived: active when the set is non-empty),lastSelectedIndexfor shift-range selection.sortField/sortDirectionfor the Archive tab.Data is fetched per tab:
/api/creator/list-quests,/api/creator/list-adventures,/api/creator/list-archived;archiveReloadre-triggers the archive fetch on retry.
View mode persistence (PR #759): stored in localStorage under wyzquests:creator:my-content-view-mode; initialized to "grid" to avoid SSR hydration mismatch, then applied in a mount effect.
Filter pipeline (order matters): filterBySkills(contentList) → status filter → search filter → (Archive only) sortArchivedItems. Search matches a lowercased haystack of title + introduction + tags[] + skills[] with includes(query).
Data model:
Creator Hub reads/writes three primary tables plus supporting tables. Relevant columns and migrations:
Table | Columns used by Creator Hub | Migration |
|---|---|---|
|
|
|
|
| same as above |
| folder names joined for the |
|
|
|
|
| per-creator asset rows cleaned up on permanent delete | — |
|
| — |
Key constraints:
publishing_statusCHECK allows('published', 'draft', 'archived')on both tables; the additional review states (submitted,in_review,changes_requested,approved) are used by the wider review flow and are typed intypes/creator.d.ts.skills TEXT[] DEFAULT '{}'with GIN indexesidx_quests_skills/idx_adventures_skills.archived_at TIMESTAMPTZwith indexesidx_quests_archived_at/idx_adventures_archived_at; drives the 120-day countdown.RLS on
quests/adventurescontinues to enforcecreator_idownership; archived rows retain the same owner.
API Specification:
URLs below are the effective paths. Next.js route groups such as (content) do not appear in the URL. All endpoints return the ApiResponseHelper envelope and are scoped by agencyResourceFilter.
Envelope shape (lib/api/response.ts):
// success{ success: true, message: string, data: { ... } } // error{ success: false, error: { message: string, details?: unknown } }
GET /api/creator/analytics — dashboard metric counts.
// app/api/creator/analytics/route.ts// QUEST = quests where publishing_status != 'archived'// PUBLISHED = quests where publishing_status = 'published'// DRAFT = QUEST - PUBLISHED// ADVENTURE = adventures where publishing_status != 'archived'{ success: true, data: { counts: { QUEST, PUBLISHED, DRAFT, ADVENTURE } } }
GET /api/creator/list-quests — non-archived quests for the dashboard/hub.
// Optional query params// ?quest_mode=linear|exploration -> filter by editor mode// ?editable_only=true -> exclude 'submitted' and 'in_review'// Rows are ordered by updated_at DESC, created_at DESC, and expose// created_at/updated_at (added by PR #759 for the list view).// Response:{ success: true, data: { questList: ContentListObject[], currentUserId: string } }
GET /api/creator/list-adventures — non-archived adventures, enriched with per-adventure total fees.
{ success: true, data: { advList: ContentListObject[], currentUserId: string } }// total_quest_fee is computed via computeAdventureTotalFees(ids)
GET /api/creator/list-archived — archived quests and adventures combined.
{ success: true, data: { archivedQuests: ContentListObject[], archivedAdventures: ContentListObject[] } }// each row includes archived_at (countdown source)
PATCH /api/creator/archive-content — soft-delete into the Archive.
// Request (single or bulk){ content_type: "quests" | "adventures", content_id?: string, content_ids?: string[] }// Effect: publishing_status = 'archived', archived_at = now(), updated_at = now()// Skips already-archived ids; returns them in skippedIds.{ success: true, data: { archivedIds: string[], missingIds: string[], skippedIds: string[] } }
PATCH /api/creator/restore-content — restore an archived item.
// Request{ content_type: "quests" | "adventures", content_id?: string, content_ids?: string[] }// Effect: publishing_status = 'draft', archived_at = null, folder ids reset to null// (restored items return to Root).{ success: true, data: { restoredIds: string[], missingIds: string[], skippedIds: string[] } }
DELETE /api/creator/permanent-delete — hard delete from the Archive.
// Request{ content_type: "quests" | "adventures", content_id?: string, content_ids?: string[], confirm_text: "DELETE" // must match exactly for single AND bulk}// Effects (per item): ownership/folder check -> typed-confirm check ->// DB delete -> storage cleanup (public-assets/{quests|adventures}/{id})// -> asset_metadata cleanup scoped to the ITEM'S creator_id.// Invalid confirm_text writes an audit_logs row (PERMANENT_DELETE_FAILED)// and returns 400.{ success: true, data: { deletedIds: string[], missingIds: string[] } }
GET /api/creator/quest-status — review-lock polling.
// ?quest_id=<uuid>{ success: true, data: { quest_id, title, publishing_status } }// Used by components/creator/quest-editor/ReviewLockOverlay.tsx, which polls// every 30s while a quest is 'submitted' | 'in_review' and reloads when the// status changes.
GET /api/creator/list-content-folders — folder list used by the library/folder pickers referenced from the dashboard's View Library entry point.
Logic & Workflows:
Dashboard load.
CreatorAnalyticCardsfetches/api/creator/analyticsonce.MyContentfetches the active tab and writes normalized rows (ContentListObject+contentType) intocontentList. Loading renders skeleton cards/rows; errors render a Retry; empty states distinguish "No current content" from "No content matches the selected filters."Search, status, skills, sort. All filtering is client-side over the loaded tab (no server round-trip). Skills use OR semantics. Clearing search, changing status, toggling a skill, or switching tabs calls
clearSelection(). Tabs resetsearchQueryandstatusFilter.View mode. Grid renders
ContentCardinxl:grid-cols-3; list rendersContentListRowwith thumbnail, type, tags, and created/updated dates. The choice persists per device vialocalStorage.Selection & bulk. Selection mode is derived from a non-empty
selectedIdsset. Shift-click selects a contiguous range over the filtered list.SelectionActionBarappears while items are selected and offers Select all / Deselect all / Archive (on Quests & Adventures) / Restore (Archive tab only) / Delete. Bulk delete opensConfirmDestructiveModalwithconfirmToken="DELETE"and lists the selected titles.Archive.
ContentCard/ContentListRowcallPATCH /api/creator/archive-content. The server verifies ownership or folder-management rights per item, excludes already-archived rows, setspublishing_status='archived'andarchived_at=now(). The client optimistically removes the archived ids from the list and toasts success.Archive tab (retention).
TrashContentrenders each item withgetDaysRemaining(archived_at)and a badge ("Nd left" or "Today");daysLeft <= 3renders the destructive "expiring soon" style. Items show Restore and Delete Forever (delete opens the typed-confirm modal). The Archive tab also supports search/status/skills filtering and its own sort dropdown.Restore.
PATCH /api/creator/restore-contentsetspublishing_status='draft', clearsarchived_at, and resetsquest_folder_id/adventure_folder_id/project_folder_idtonullso the item returns to Root. Non-archived ids are returned inskippedIds.Permanent delete.
DELETE /api/creator/permanent-deleterequiresconfirm_text === "DELETE". On success it deletes the DB rows, cleanspublic-assets/{quests|adventures}/{id}and matchingasset_metadatarows using the item's owncreator_id(so a folder admin deleting a colleague's item does not orphan that colleague's metadata), then returnsdeletedIds. A wrong confirmation token logs toaudit_logswith actionPERMANENT_DELETE_FAILEDand returns HTTP 400. Bulk delete in the Archive tab splits quests and adventures into two requests.Review lock. When a quest is
submittedorin_review, the editor rendersReviewLockOverlay, which callsGET /api/creator/quest-statuson mount and every 30 seconds, and refreshes the page once the status leaves the review states.Archive auto-purge (background).
GET /api/cron/purge-expired-archived(secured byCRON_SECRET) deletes archive rows older thanARCHIVE_RETENTION_DAYS(120) and their assets vialib/archive/purgeArchivedContent.ts./api/cron/check-pending-deletionemits warnings for items approaching expiry.
Helpers & shared services:
Helper | Location | Use |
|---|---|---|
|
| Resolve creator context (wraps |
|
| Build the |
|
| Per-item ownership check for mutations |
|
| Folder-admin fallback authorization |
|
| Standardized success/error envelope |
|
| Zod validation for content mutations |
|
| Adventure |
|
| Fallback cover + session-stable cache-busting (PR #690) |
|
| Archive countdown |
|
| Archive sort field/direction |
|
| Unique skills + OR filter |
INFRASTRUCTURE & OPERATIONS
Dependencies:
The hub depends on stable project generation and management:
#70 — [1.1] Project Creation (closed)
#71 — [2.1] Form Editor (closed)
Runtime dependencies:
Supabase project (Auth + Postgres + Storage
public-assets); service credentials in server env.CRON_SECRETfor the archive purge/check endpoints.Agency/ownership tables (
app_users,user_roles,agency_members,agencies) must be populated foragencyResourceFilterto scope correctly.
Monitoring & Alerting:
Server handlers log failures via
console.error(e.g.,[ARCHIVE] Update failed,Fetch Quest Error); these flow to the hosting platform's log stream./api/cron/purge-expired-archivedand/api/cron/check-pending-deletionreturn structured JSON (type, per-tabledeleted,errors) for cron monitoring.Destructive-token failures are persisted to
audit_logs(PERMANENT_DELETE_FAILED) for after-the-fact review.No dedicated dashboard/alerting is wired to the Creator Hub today; this remains a follow-up.
Deployment Plan:
Ensure the
questsandadventurestables exposepublishing_status,archived_at, andskills(migrations20260209100000_*,20260728_*).Ensure all migrations for folders (
quest_folders,adventure_folders,project_folders,folder_permissions) are applied sofolderNameand folder-admin checks resolve.Configure
CRON_SECRETand schedule/api/cron/purge-expired-archived//api/cron/check-pending-deletion.Verify each card/row redirects to the correct editor: quests →
/quest-editor/{id}, adventures →/creator/edit-adventure/{id}.Verify responsive behavior at mobile and desktop breakpoints.
Deploy to production after the Playwright creator suite passes.
Archive retention: 120 days (ARCHIVE_RETENTION_DAYS). The purge cutoff is now - 120 days; the card badge turns destructive at <= 3 days remaining.
TESTING & QUALITY ASSURANCE
Testing Strategy:
Primary coverage is Playwright end-to-end under tests/e2e/creator/:
archive-restore-delete.spec.ts— archive → restore → countdown/delete flows (note: uses the historical "Trash" wording; see Known Limitations).permanent-delete.spec.ts— QA-024: archive a quest from Quests, then permanently delete it from the Archive tab.skill-tags.spec.ts— skills assignment/filtering.project-creation.spec.ts,quest-creation.spec.ts,enrollment.spec.ts— surrounding creator flows that exercise the dashboard entry points.publish-ai-scenario.spec.ts,embed-html.spec.ts,delete-node.spec.ts— related creator surfaces.
Manual/functional checks:
Analytics counts match the non-archived quest total, published total, derived drafts, and adventure total.
Search matches title, introduction, tags, and skills; matches are case-insensitive.
Grid/list toggle persists across reloads.
Shift-click range selection and bulk archive/restore/delete behave on the filtered list.
Permanent delete rejects any token other than
DELETEand writes an audit row.Restored items reappear at Root (folder ids cleared) as drafts.
Known Limitations:
Search and filtering are client-side over the loaded tab. Very large libraries are bounded by the list endpoints' returned rows; there is no server-side pagination or search.
View-mode preference is stored per device/browser (
localStorage), not per account.The third tab is labeled Archive, but the component is still named
TrashContentand some tests/toasts use the historical "Trash"/"moved to Trash" wording — a cosmetic naming inconsistency, not a behavior gap.Dashboard cards do not surface folder organization; folder management is in the Content Library.
Assets whose
creator_idcannot be resolved during permanent delete fall back to the requester's id forasset_metadatacleanup.No dedicated monitoring dashboard/alerting for the hub.
MAINTENANCE & SUPPORT
Troubleshooting:
Empty or wrong lists: confirm
agencyResourceFilteris returning a usable.or(...)clause and thatapp_users/agency rows exist for the caller. Check for Zod/regex validation errors in the handler logs.Archive/delete returns 403: the caller is neither the owner nor a folder manager for the item's folders. Inspect
getCreatorAuthContextandcanManageItemsInFolders.Permanent delete returns 400 "Please type DELETE":
confirm_textdid not exactly equalDELETE; anaudit_logsrow should exist.Countdown wrong / item never purged: verify
archived_atis set (archive-content) and that the cron hasCRON_SECRETand is scheduled.Stale card image:
getImageUrlcache-busts with a session-stable timestamp; a hard reload should refresh.handleImageErrorfalls back to/images/default-quest-cover.svg.Quest stays locked under review:
ReviewLockOverlaypollsGET /api/creator/quest-status; confirm the route is reachable and the quest's status actually changed.
Changelog:
2.0 — 2026-10-01 — Internal Technical Guide overhaul (Updated by: Patrick Babala)
Rewrote the guide against the current codebase; filled "Logic & Workflows," monitoring, dependencies, and limitations (previously placeholders).
Documented search + grid/list view mode and the Archive tab (Issues #661, #662; PR #759).
Documented the non-locking status filter fix (PR #767).
Documented 16:9 thumbnails, list scroll fix, and image cache-busting (PR #690).
Documented the reusable typed-confirmation destructive modal and
DELETEtoken + audit logging (PR #780).Corrected Clerk → Supabase Auth; corrected/expanded the API specification; added the data model, helpers, archive-retention, and troubleshooting sections; fixed the References list (#77 + #661 + #662).
Replaced the original 3-box diagram with a layered architecture diagram built from code.
1.0 — 2026-04-06 — James Derick Billate
Initial draft; feature existed on the dev server before and after initial dev review.
Document version: 2.0 — Updated (live), 2026-10-01. Original: 1.0 — Draft, 2026-04-06.