Feature Owner: Joshua Uriel Tribiana
Updated by: Christian Denzon (archive overhaul — 120-day retention, day-90 warning + day-120 auto-purge crons, bulk actions, archive sort and toolbar; July – September 2026)
Module: Develop (Content Production)
Priority: P1
Status: Shipped — Approved and Merged
Date: 07/03/2026
Last Updated: September 30, 2026
Companion document: engineering detail (database schema, API contracts, cron internals, authorization helpers) lives in the Archive Asset Internal Technical Guide. This Hand-Off is product-facing and cross-references it instead of duplicating it.
Executive Summary
What is this feature?
Archive Asset gives creators a safe, reversible deletion path for the content they produce. Quests, adventures, and background assets are no longer deleted outright: the first action moves them to Archive (a soft delete), and they stay restorable for 120 days. Thirty days before the retention window ends, each creator receives one email listing everything that is about to expire, and anything not restored is permanently purged on day 120.
The feature originally shipped as a “Trash” workflow for background assets with a 30-day window (v1.0). As of v2.0 it covers quests and adventures as well, the surface is named Archive everywhere, the window is 120 days, and the retention lifecycle runs automatically.
Why does it matter?
Creators need safer deletion behaviour to avoid accidental permanent loss. Archive lowers the support burden, improves trust in content operations, and provides a controlled lifecycle before purge — instead of an irreversible click.
What’s the MVP scope?
Move a background asset, quest, or adventure to Archive (soft delete) from the creator dashboard.
Two Archive surfaces: the Archive tab in the content library (quests + adventures) and
/creator/archive(background assets).Countdown badge on every archived card showing days left (turns red at 3 days or fewer).
Restore archived items to the active library at any time before purge. Restored quests and adventures return to the top level of the library.
Permanent delete stays a separate, explicitly confirmed destructive action (typed
DELETE).Bulk Archive / Restore / Delete through the selection action bar (shipped with sub-issue #727 / PR #728 — see the Bulk Actions Hand-Off).
Automatic retention automation: a day-90 warning email; a day-120 purge of anything still archived.
Archive filtering and sorting: search, status filter, skills filter, grid/list view, and Sort by (Days Left / Alphabetical).
1. User Pain Point & Solution
Current State (Without Feature)
Deleting a background asset, quest, or adventure risks immediate permanent loss or inconsistent recovery options. Content in use elsewhere can disappear without a trace, and there is no reminder before anything is removed for good.
Pain Point
Emotional: Anxiety over accidental deletion — creators hesitate to clean up.
Functional: No safe recovery window for removed content; no advance notice before permanent removal.
Business Impact: Creator friction, abandoned-library clutter, and avoidable support tickets.
Future State (With Feature)
Any archive action moves the item into Archive with a 120-day retention marker and a visible countdown. Creators can restore at any time before the deadline, receive one reminder email 30 days before removal, and only lose the item if they ignore both the countdown and the email.
Marketing Hook
“Delete with confidence: a 120-day safety net, one-click restore, and a reminder before anything disappears.”
2. 4D Framework Mapping
Diagnose: Surfaces where deletion risk happens in the creator content and asset workflow — quests, adventures, and background assets, on both the dashboard and the background-assets page.
Design: A two-step lifecycle — archive first, purge later — with a 120-day window, a countdown badge, and a warning email at day 90.
Develop: API and UI behaviour for soft-delete, archive retrieval, restore, permanent delete, bulk actions, archive sorting, and the two retention cron jobs.
Deliver: Safer operations in production creator environments with reduced accidental data loss and an automated, auditable retention path.
3. User Flows
Entry Points:
Creator dashboard → Quests or Adventures tab → Archive on a card.
Creator dashboard → Archive tab (quests + adventures).
Background Assets page → Archive button on an asset card, or the Archive link in the header.
Any archive surface → selection action bar (bulk Restore / Delete).
Email → “Go to Archive” call to action in the day-90 warning.
Success Criteria: A creator can archive any quest, adventure, or background asset; see it move out of the active list into Archive with the days remaining; restore it at any time before the 120-day window ends; permanently delete it through a typed confirmation; and manage several items at once. Nothing is purged without a prior warning email.
Main Flow (Happy Path):
Creator chooses Archive on a quest/adventure card (or an asset card in Background Assets).
The confirmation modal explains the action and the retention window (“You can restore it anytime within the next 120 days.”).
The API records the archive state and the archive timestamp.
The item disappears from the active list and appears in Archive with a countdown badge.
On day 90 the creator receives one email listing every item expiring within 30 days.
The creator opens Archive (or the email link), selects the item, and chooses Restore — the item returns to the active library.
Anything still archived that reaches day 120 is permanently purged automatically.
Edge Cases:
No data: the Archive tab shows “Archive is empty / Archived projects will appear here”;
/creator/archiveshows “Your archive is empty”.No filter matches: the Archive tab shows “No content matches the selected filters”.
API error: a toast is shown and the item stays unchanged in the UI (state is updated only after a successful response).
Permission denied: the API rejects the request and the UI surfaces the error.
Already archived: archiving an already-archived item is rejected with “Content is already archived” / “Assets are already archived”.
Not archived: restoring an item that is not archived is rejected with “Content is not archived” / “Assets are not archived”.
Expiring soon: the countdown badge turns destructive-coloured at 3 days or fewer and reads “Today” at zero.
No email address on the account: the item is skipped by the warning run and stays eligible for the next run.
Missed cron run: the warning job is not time-window based — un-warned items are picked up on the next daily run.
Archived quest opened in the editor: the quest opens read-only with a banner instructing the creator to restore it from the Archive tab.
Asset still referenced by a quest: there is no in-use guard — archiving and purging are allowed even if the asset is referenced elsewhere (see Open Questions).
Decision Points:
IF the creator confirms Archive → the soft-delete API runs.
ELSE the modal closes with no state change.
IF the creator chooses Restore → the archive fields are cleared and, for quests/adventures, the item also returns to the top level of the library.
IF the creator chooses Delete Permanently and types
DELETE→ the storage object(s) and the metadata row are removed.IF the confirmation token does not match → the API refuses and the item is untouched.
4. Information Architecture
Primary Information (Always visible):
Item name (quest, adventure, or asset file name).
Preview / thumbnail.
Item type (quest, adventure, or asset type such as IMAGE / AUDIO / VIDEO / DOCUMENT).
Archived state and days remaining (Archive surfaces only).
Secondary Information:
Remaining days until retention expiry (countdown badge).
Source and file size metadata (assets).
Publishing status, skills, and tags (quests / adventures).
Adventure total fee (content archive list).
Tertiary Information (Hidden until needed):
Internal IDs (
asset_id,content_id).Storage file paths.
Ownership and agency scope filters.
Warning-tracking state (whether the day-90 email has already been sent).
Actions:
Primary CTA:
Archive (assets: “Move to Archive”)
Secondary Actions:
Restore
Delete Permanently (assets) / Delete Forever (quests + adventures)
Edit asset name
Bulk actions via the selection action bar: Restore and Delete (Archive surfaces); Archive and Delete on active surfaces
Sort the archive: Days Left / Alphabetical
Switch between grid and list view
5. Data Requirements
Route-level contracts, response envelopes, and field mappings are documented in the Archive Asset Internal Technical Guide → API Specification.
Frontend Needs:
Item identifiers and names.
URLs / thumbnails for display.
The archive timestamp (
deleted_atfor assets,archived_atfor quests/adventures) to derive the countdown.Asset type and size metadata.
Publishing status and skills for the content archive list.
API Calls Frontend Will Make:
GET /api/creator/list-assetson Background Assets load.DELETE /api/creator/delete-assetson archive (single or bulk).GET /api/creator/get-trash-assetson/creator/archiveload.PATCH /api/creator/restore-assetson restore (single or bulk).DELETE /api/creator/purge-assetson permanent delete (single or bulk).PATCH /api/creator/archive-contenton quest/adventure archive.PATCH /api/creator/restore-contenton quest/adventure restore.DELETE /api/creator/permanent-deleteon quest/adventure permanent delete.GET /api/creator/list-archivedon the Archive tab load.
Caching Strategy:
No-store fetch patterns are used for freshness on archive and active listings; the list routes are forced dynamic so an archive or restore is reflected immediately.
6. Performance Considerations
Database Optimization:
Archive filtering is indexed (
deleted_atfor assets;archived_atfor quests/adventures).Creator ownership lookups are indexed by
creator_id.Partial indexes cover the retention scans performed by the cron jobs (only un-warned archived rows).
Query Optimization Notes:
Active and archive lists are split by clear predicates (
IS NULL/IS NOT NULL;publishing_status = 'archived').The purge job processes quests, adventures, and assets in parallel, and storage cleanup per item runs with
Promise.allSettledso one failure cannot block the batch.
API Response Time:
Target: sub-1s for standard list and archive operations under normal load. Bulk actions scale with the number of selected IDs, not with page size.
7. Security & Authorization
Who Can Access This Feature?
Creator: Full access to their own content and background assets.
Agency Admin / Agency Owner: Agency-scoped access to their members’ content and assets.
Platform Admin: Access, including the View As preview of the creator UI.
Reviewer: No access.
Learner: No access.
Authorization Logic:
An authenticated creator context is required on every archive route.
Ownership is verified per item, not per request, before any archive, restore, or purge.
Quests and adventures additionally accept the folder-permission fallback: a folder owner/admin may archive, restore, or delete content inside their folders even when another creator owns it.
Background assets are creator/agency scoped only — there is no folder fallback.
The scheduled retention jobs are protected by a shared
CRON_SECRETand are not reachable by end users.
Data Validation:
Single IDs and ID arrays are validated as UUIDs with Zod on archive/restore/purge routes.
Permanent deletion requires the typed confirmation token
DELETE, validated again on the server.Server-side ownership checks prevent cross-tenant operations.
8. Error Handling
400 → Invalid payload, already-archived item, not-archived item, or a wrong
DELETEtoken. Toast explains the problem; item state unchanged.401 → Not authenticated. Redirect to sign-in.
403 → Not the owner and not a folder manager. Toast error; no mutation.
404 → Item missing or inaccessible. Toast error; item remains in the list.
500 → Database or storage failure. Generic toast (“Failed to archive asset”, “Failed to delete asset completely”, “Failed to load archive”); client state unchanged.
Cron-specific → a missing
CRON_SECRETreturns 500 and a mismatched secret returns 401; a non-200 response fails the GitHub Actions job so the failure is visible in the run history.
9. Testing Checklist
Happy Path:
Archive a background asset → it disappears from Background Assets and appears in
/creator/archivewith a countdown badge.Archive a quest and an adventure → both disappear from their tabs and appear in the Archive tab with countdown badges.
Restore an asset → it returns to Background Assets.
Restore a quest → it returns to the Quests tab at the top level (folder association cleared).
Run the purge cron → archived items past the retention cutoff are permanently deleted, and their storage objects are gone.
Bulk-select several items on an active surface → Archive and Delete work from the action bar.
Bulk-select on an archive surface → Restore and Delete work from the action bar.
Sort the archive by Days Left and by Alphabetical, ascending and descending.
Edge Cases:
Empty archive states render correctly on both surfaces.
Filtering the Archive tab until nothing matches shows “No content matches the selected filters”.
Countdown badge shows 3 days or fewer in the destructive colour, and “Today” at zero.
API timeout/error shows user-safe feedback and leaves the item in place.
Ownership mismatch blocks the mutation.
Invalid UUID payload returns 400.
Permanent delete without typing
DELETEis refused.Archiving an already-archived item and restoring a non-archived item are both refused.
Archived quest opened in the editor is read-only and shows the restore banner.
Day-90 warning email: one email per creator listing every expiring item; agency branding applied; already-warned items are not emailed twice.
Re-running a cron after a failure catches items that were missed.
10. OPEN QUESTIONS
Should the retention countdown use
expires_atdirectly instead of deriving it fromdeleted_at? — Resolved (v2.0): the countdown is derived from the archive timestamp (deleted_at/archived_at) as the single source of truth.expires_atis still written when an asset is archived, but the countdown and both crons key off the archive timestamp so a manualexpires_atedit cannot change behaviour.Should trash operations support optimistic UI with rollback for failures? — Resolved (v2.0, current behaviour): no optimistic UI. Items are removed from the list only after a successful server response, so there is nothing to roll back.
Should typed DELETE confirmation be enforced server-side for the purge endpoint? — Resolved (v2.0): yes. The server requires
confirm_text = "DELETE"for both asset purges and quest/adventure permanent deletes, and records a failed attempt in the audit log.Should an automatic retention job purge expired assets based on
expires_at? — Resolved (v2.0): yes, the automatic purge shipped (PR #770), but keyed offdeleted_at/archived_atrather thanexpires_at; it covers quests, adventures, and assets.New (v2.0) — Still open: should archiving or purging an asset that is still referenced by a quest or activity be blocked or warned about? There is currently no in-use guard.
New (v2.0) — Still open: should the day-90 warning be repeatable (e.g. a reminder at 7 days), or is the single reminder enough?
11. OUT OF SCOPE
Not building:
Automatic scheduled purge worker.Shipped (v2.0): the day-120 purge and the day-90 warning both run automatically as daily scheduled jobs.Admin-level retention policy customization. Still out of scope: retention is fixed at 120 days for all creators and all content types.
An additional recovery window after purge (no second bin). Still out of scope: purge is irreversible.
12. SUCCESS METRICS
How will we know this feature is successful?
Archive and restore operations succeed reliably in production.
Retention automation runs daily without manual intervention; creators receive exactly one warning per expiring item.
Reduction in accidental permanent deletion incidents.
Lower support cases related to missing background assets, quests, or adventures.
Creators actually use the safety net: a meaningful share of archived items are restored before day 120.
18. DEPENDENCIES
This feature depends on:
The
asset_metadatatable plus the archive columns onquestsandadventures(migrations).Supabase storage integration (bucket
public-assets) for uploads and purge cleanup.Agency ownership authorization helpers for per-item ownership checks.
The email service and the
AutoDeletionWarningEmailtemplate for the day-90 warning.GitHub Actions scheduled workflows plus the
CRON_SECRETconfigured on the servers and as a repository secret.Folder permissions (MFPS) for the folder-admin fallback on quests and adventures.
These features depend on this:
Archive behaviour for quests, adventures, and background assets across the creator dashboard.
Safe asset lifecycle controls before permanent deletion (including the shared destructive-confirmation standard).
The Bulk Actions feature, which acts on the archive surfaces (Restore / Delete) and on the active surfaces (Archive / Delete).
19. TIMELINE & OWNERSHIP
Implementation
Backend: Christian Denzon — delivered (PRs #711, #725, #770, #794)
Frontend: Christian Denzon — delivered (same PRs, plus bulk selection in #728)
Retention automation: Christian Denzon — delivered (#770, hardened in #794)
QA: Internal development testing.
Document version: 2.0 — Hand-off updated for the archive overhaul (Trash → Archive rename, 120-day retention, day-90 warning and day-120 auto-purge crons, bulk actions, archive sort and toolbar), September 30, 2026. PRs: #711, #725, #770, #794. Sub-issue #727 / PR #728 is documented in the Bulk Actions Hand-Off.