[5.3] Creator Hub

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 LearnerGroupAnalytics summary 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-assets bucket), Supabase Auth (authentication)

    • Correction: the original guide listed "Clerk Authentication". The platform migrated to Supabase Auth. The app_users.clerk_id column name is retained for legacy compatibility and stores the Supabase user id.

  • Tailwind CSS for styling; Radix UI primitives (DropdownMenu, Popover, Tooltip) for menus/filters

  • Zod for request validation; ApiResponseHelper for the standardized API envelope

  • dnd-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:

  1. Route guard. app/creator/layout.tsx calls authenticateAnyRole(["CREATOR", "ADMIN"]) and applies the View-As redirect before rendering CreatorLayoutClient, which provides the UnifiedSidebar, Header, CreatorContext, and BrandingProvider.

  2. Dashboard composition. app/creator/page.tsx is a client component laid out as grid xl:grid-cols-7: a 5-column main column (CreatorHeader, CreatorAnalyticCards, LearnerGroupAnalytics, MyContent) and a 2-column right rail (RecentActivity, AISuggestion). ModalCreate is mounted here as an overlay driven by CreatorContext.isModalActive.

  3. API layer. All creator APIs live under app/api/creator/*. Every handler first calls getCreatorAuthContext(), then applies agencyResourceFilter(authContext) (.or(...)) so a creator sees their own content plus content owned by users in their agency, per the caller's role. Mutations additionally run verifyAgencyResourceOwnership per item and fall back to canManageItemsInFolders for folder administrators.

  4. Response envelope. All endpoints return the ApiResponseHelper shape; clients read data?.data ?? data for forward compatibility.


DETAILED DESIGN & IMPLEMENTATION

Frontend components:

Component

File

Responsibility

Creator (page)

app/creator/page.tsx

Dashboard grid, View-As overlay, ModalCreate

CreatorLayoutClient

app/creator/CreatorLayoutClient.tsx

Sidebar/header shell, CreatorContext, BrandingProvider

CreatorHeader

components/creator/CreatorHeader.tsx

Title, Create Content, AI Assistant actions; opens ModalCreate

CreatorAnalyticCards

components/creator/CreatorAnalyticCards.tsx

Four metric cards from /api/creator/analytics

LearnerGroupAnalytics

components/creator/LearnerGroupAnalytics.tsx

Learner-group summary widget

MyContent

components/creator/MyContent.tsx

Tabs, search, filters, view mode, selection, bulk actions, data loading

ContentCard

components/content-library/ContentCard.tsx

Grid card: cover, badges, tags, folder badge, archive/delete/edit

ContentListRow

components/creator/ContentListRow.tsx

List-view row (PR #759): thumbnail, tags, created/updated dates, actions

TrashContent

components/creator/TrashContent.tsx

Archive tab: countdown, restore, permanent delete, bulk restore/delete

SelectionActionBar

components/creator/SelectionActionBar.tsx

Floating bulk-action bar (select all / deselect / archive / restore / delete)

ConfirmDestructiveModal

components/shared/confirm-destructive-modal.tsx

Reusable typed-confirmation modal (PR #780)

ArchiveSortDropdown

components/creator/ArchiveSortDropdown.tsx

Archive sort field/direction

useSkillsFilter

hooks/creator/useSkillsFilter.ts

Extracts unique skills and applies OR filtering (W1.3)

MyContent state model:

  • shownContent: "quests" | "adventures" | "archive" — tabs. The third tab is labeled Archive (TrashContent renders 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), lastSelectedIndex for shift-range selection.

  • sortField / sortDirection for the Archive tab.

  • Data is fetched per tab: /api/creator/list-quests, /api/creator/list-adventures, /api/creator/list-archived; archiveReload re-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

quests

id, creator_id, title, introduction, tags, skills[], profile_img_url, publishing_status, duration, enrollment_fee, display_price, quest_mode, quest_folder_id, project_folder_id, archived_at, created_at, updated_at

20260209100000_add_skills_and_archived_status.sql; 20260728_add_archived_at_to_quests_adventures.sql

adventures

id, creator_id, title, introduction, tags, skills[], profile_img_url, publishing_status, duration, enrollment_fee, display_price, adventure_folder_id, project_folder_id, archived_at, created_at, updated_at

same as above

quest_folders / adventure_folders / project_folders

folder names joined for the folderName badge

20260421_*, 20260504_create_quest_folder.sql, 20260512_add_project_folder_to_adventures.sql

folder_permissions

permission_level for canManageItemsInFolders

20260521025258_add_folder_permissions.sql

asset_metadata

per-creator asset rows cleaned up on permanent delete

—

audit_logs

PERMANENT_DELETE_FAILED entries

—

Key constraints:

  • publishing_status CHECK 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 in types/creator.d.ts.

  • skills TEXT[] DEFAULT '{}' with GIN indexes idx_quests_skills / idx_adventures_skills.

  • archived_at TIMESTAMPTZ with indexes idx_quests_archived_at / idx_adventures_archived_at; drives the 120-day countdown.

  • RLS on quests/adventures continues to enforce creator_id ownership; 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:

  1. Dashboard load. CreatorAnalyticCards fetches /api/creator/analytics once. MyContent fetches the active tab and writes normalized rows (ContentListObject + contentType) into contentList. Loading renders skeleton cards/rows; errors render a Retry; empty states distinguish "No current content" from "No content matches the selected filters."

  2. 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 reset searchQuery and statusFilter.

  3. View mode. Grid renders ContentCard in xl:grid-cols-3; list renders ContentListRow with thumbnail, type, tags, and created/updated dates. The choice persists per device via localStorage.

  4. Selection & bulk. Selection mode is derived from a non-empty selectedIds set. Shift-click selects a contiguous range over the filtered list. SelectionActionBar appears while items are selected and offers Select all / Deselect all / Archive (on Quests & Adventures) / Restore (Archive tab only) / Delete. Bulk delete opens ConfirmDestructiveModal with confirmToken="DELETE" and lists the selected titles.

  5. Archive. ContentCard / ContentListRow call PATCH /api/creator/archive-content. The server verifies ownership or folder-management rights per item, excludes already-archived rows, sets publishing_status='archived' and archived_at=now(). The client optimistically removes the archived ids from the list and toasts success.

  6. Archive tab (retention). TrashContent renders each item with getDaysRemaining(archived_at) and a badge ("Nd left" or "Today"); daysLeft <= 3 renders 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.

  7. Restore. PATCH /api/creator/restore-content sets publishing_status='draft', clears archived_at, and resets quest_folder_id/adventure_folder_id/project_folder_id to null so the item returns to Root. Non-archived ids are returned in skippedIds.

  8. Permanent delete. DELETE /api/creator/permanent-delete requires confirm_text === "DELETE". On success it deletes the DB rows, cleans public-assets/{quests|adventures}/{id} and matching asset_metadata rows using the item's own creator_id (so a folder admin deleting a colleague's item does not orphan that colleague's metadata), then returns deletedIds. A wrong confirmation token logs to audit_logs with action PERMANENT_DELETE_FAILED and returns HTTP 400. Bulk delete in the Archive tab splits quests and adventures into two requests.

  9. Review lock. When a quest is submitted or in_review, the editor renders ReviewLockOverlay, which calls GET /api/creator/quest-status on mount and every 30 seconds, and refreshes the page once the status leaves the review states.

  10. Archive auto-purge (background). GET /api/cron/purge-expired-archived (secured by CRON_SECRET) deletes archive rows older than ARCHIVE_RETENTION_DAYS (120) and their assets via lib/archive/purgeArchivedContent.ts. /api/cron/check-pending-deletion emits warnings for items approaching expiry.

Helpers & shared services:

Helper

Location

Use

getCreatorAuthContext

lib/auth/agencyOwnership.ts

Resolve creator context (wraps getAgencyAuthContext + verifyCreatorAccess)

agencyResourceFilter

lib/auth/agencyOwnership.ts

Build the .or(...) filter (creator id / agency id set)

verifyAgencyResourceOwnership

lib/auth/agencyOwnership.ts

Per-item ownership check for mutations

canManageItemsInFolders

lib/folder/folderAccess.ts

Folder-admin fallback authorization

ApiResponseHelper

lib/api/response.ts

Standardized success/error envelope

archiveContentSchema / restoreContentSchema / permanentDeleteSchema

shared/schemas/contentManagementSchema.ts

Zod validation for content mutations

computeAdventureTotalFees

lib/quest/adventureTotalFees.ts

Adventure total_quest_fee enrichment

getImageUrl / handleImageError

lib/utils/default-image.ts

Fallback cover + session-stable cache-busting (PR #690)

getDaysRemaining / ARCHIVE_RETENTION_DAYS

lib/archive/getDaysRemaining.ts

Archive countdown

sortArchivedItems

lib/archive/sortArchivedItems.ts

Archive sort field/direction

useSkillsFilter

hooks/creator/useSkillsFilter.ts

Unique skills + OR filter


INFRASTRUCTURE & OPERATIONS

Dependencies:
The hub depends on stable project generation and management:

Runtime dependencies:

  • Supabase project (Auth + Postgres + Storage public-assets); service credentials in server env.

  • CRON_SECRET for the archive purge/check endpoints.

  • Agency/ownership tables (app_users, user_roles, agency_members, agencies) must be populated for agencyResourceFilter to 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-archived and /api/cron/check-pending-deletion return structured JSON (type, per-table deleted, 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:

  1. Ensure the quests and adventures tables expose publishing_status, archived_at, and skills (migrations 20260209100000_*, 20260728_*).

  2. Ensure all migrations for folders (quest_folders, adventure_folders, project_folders, folder_permissions) are applied so folderName and folder-admin checks resolve.

  3. Configure CRON_SECRET and schedule /api/cron/purge-expired-archived / /api/cron/check-pending-deletion.

  4. Verify each card/row redirects to the correct editor: quests → /quest-editor/{id}, adventures → /creator/edit-adventure/{id}.

  5. Verify responsive behavior at mobile and desktop breakpoints.

  6. 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 DELETE and 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 TrashContent and 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_id cannot be resolved during permanent delete fall back to the requester's id for asset_metadata cleanup.

  • No dedicated monitoring dashboard/alerting for the hub.


MAINTENANCE & SUPPORT

Troubleshooting:

  • Empty or wrong lists: confirm agencyResourceFilter is returning a usable .or(...) clause and that app_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 getCreatorAuthContext and canManageItemsInFolders.

  • Permanent delete returns 400 "Please type DELETE": confirm_text did not exactly equal DELETE; an audit_logs row should exist.

  • Countdown wrong / item never purged: verify archived_at is set (archive-content) and that the cron has CRON_SECRET and is scheduled.

  • Stale card image: getImageUrl cache-busts with a session-stable timestamp; a hard reload should refresh. handleImageError falls back to /images/default-quest-cover.svg.

  • Quest stays locked under review: ReviewLockOverlay polls GET /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 DELETE token + 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.


Was this article helpful?