Archive Node

  1. Overview
  2. Internal Technical Guides
  3. Design (Dual Editor)
  4. Archive Node

1. Front Matter

  • Title: Archive Node

  • Author: Joshua Uriel Tribiana ( Joshua-Yel )

  • Reviewers: JD Billate ( zcrnnn )

  • Creation Date: 2026-05-22

  • Status: Approved

  • References:

    • Issue: [2.5] Archive Node

2. Introduction & Goals

  • Problem Summary: Creators need a way to temporarily hide or disable nodes within the Visual Canvas without permanently deleting them. This functionality is crucial for drafting alternative paths, versioning content, or cleaning up the workspace during development without losing work. The Archive Node feature provides a non-destructive way to manage canvas complexity.

  • Goals

    • Provide a UI action to "archive" any node on the Visual Canvas.

    • Visually hide archived nodes from the main canvas view to reduce clutter.

    • Provide a separate interface (ArchivedNodesModal.tsx) to view and restore archived nodes.

    • Ensure archived nodes are excluded from the final learner experience and any SCORM exports.

    • Persist the archived state of nodes within the existing quest data structure.

  • Non-Goals

    • A full version history or "undo/redo" stack for the entire canvas.

    • The ability to archive connections (edges) independently of their nodes.

    • Automatic archiving of inactive nodes.

  • Glossary

    • Archive Node: The action of soft-deleting a node from the active canvas by setting an archived flag.

    • Visual Canvas: The editor interface where creators build the quest structure using nodes and edges.

    • Canvas Metadata: The JSONB data structure stored in the quests table that represents the state of the Visual Canvas, including all nodes and edges.

3. High-Level Architecture

  • System Diagram:

+--------------------+
| Canvas Node        |
+--------------------+
          |
          v
+--------------------+
| Context Menu       |
| Archive            |
+--------------------+
          |
          v
+--------------------+
| Status Updated     |
| (ARCHIVED)         |
+--------------------+
          |
     +----+----+
     |         |
     v         v
+-----------+  +----------------+
| Hidden    |  | Archived Nodes |
| on Canvas |  | Modal          |
+-----------+  +----------------+
                     |
                     v
              +----------------+
              | Restore Node   |
              +----------------+
                     |
                     v
              +----------------+
              | Visible Again  |
              +----------------+

  • Technologies Used:

    • React: For building the frontend components.

    • Custom Canvas / React Flow: For the visual quest editor.

    • Next.js: For API routes and server-side logic.

    • Supabase (PostgreSQL): For data persistence of the canvas_metadata in the quests table.

4. Detailed Design & Implementation

  • Data Model / Schema:
    No new database tables are introduced. The feature works by adding a boolean flag to the existing node data structure within the quests.canvas_metadata JSONB column.

    Node Object Modification:
    A new optional property, archived: boolean, is added to the data object of each node.

    Example Node JSON:

    // Before Archiving
    {
      "id": "node-123",
      "type": "Text",
      "position": { "x": 100, "y": 100 },
      "data": {
        "label": "Introduction",
        "textContent": "Welcome to the quest."
      }
    }
     
    // After Archiving
    {
      "id": "node-123",
      "type": "Text",
      "position": { "x": 100, "y": 100 },
      "data": {
        "label": "Introduction",
        "textContent": "Welcome to the quest.",
        "archived": true
      }
    }

  • API Specification
    The feature reuses the existing API for updating a quest's canvas state. No new endpoints are required.

    • Endpoint: PUT /api/creator/update-quest-canvas

    • Authentication: Required (Creator role).

    • Response: Standard success or error response for the update operation.

    • Request Body:

      {
        "quest_id": "uuid-of-the-quest",
        "canvas_metadata": {
          "nodes": "[...]", // Full array of nodes, including the one with the updated 'archived' flag
          "edges": "[...]"
        }
      }

  • Logic & Workflows

    1. Archiving a Node:

      • A user action (e.g., right-click context menu) on a node in the Visual Canvas triggers an onArchiveNode(nodeId) handler.

      • The handler finds the corresponding node in the client-side state array.

      • It updates the node object by setting node.data.archived = true.

      • The state update causes the ArchivedNodeHider.tsx component to filter this node out of the visible set rendered on the canvas.

      • A debounced save function is triggered, which sends the entire updated canvas_metadata object to the PUT /api/creator/update-quest-canvas endpoint.

    2. Restoring a Node:

      • The user opens the ArchivedNodesModal.tsx component.

      • This modal receives the full list of nodes from the canvas state and displays only those where node.data.archived === true.

      • The user clicks a "Restore" button next to a node in the list, triggering onRestoreNode(nodeId).

      • The handler finds the node in the client-side state and sets node.data.archived = false (or deletes the key).

      • The state update causes the node to reappear on the main canvas.

      • The debounced save function persists the change to the database.

Key Files:

  • components/quest-editor/visual-canvas/ArchivedNodeHider.tsx: A wrapper component that filters the nodes prop, passing only non-archived nodes to the main canvas renderer.

  • components/quest-editor/visual-canvas/ArchivedNodesModal.tsx: The UI modal for viewing and restoring archived nodes.

  • app/quest-editor/.../visual-canvas/page.tsx: The main page that holds the canvas state and the archive/restore handlers.

  • app/api/creator/update-quest-canvas/route.ts: The existing API endpoint used to persist the changes.

5. Infrastructure & Operations

  • Dependencies

    • Internal: This feature is self-contained within the WyzQuests frontend and backend. It depends on the existing quests table in the Supabase database.

    • External: None.

  • Monitoring & Alerting

    • Standard monitoring for the PUT /api/creator/update-quest-canvas endpoint applies.

    • Alerts should be configured for a high rate of 5xx errors on this endpoint, as it would impact all canvas-related features, including archiving.

  • Deployment Plan

    • Database Migrations: No database schema changes are required. The canvas_metadata JSONB column is flexible enough to accommodate the new archived flag.

    • Rollout: The feature can be deployed directly. As it's an enhancement to an existing editor, no special feature flag is required unless a phased rollout is desired for UX feedback.

6. Testing & Quality Assurance

  • Test Strategy

    • Unit Tests:

      • Test the ArchivedNodeHider component to ensure it correctly filters nodes based on the archived flag.

      • Test the state management logic for the archive and restore handlers to confirm they correctly modify the node objects.

    • Integration Tests:

      • Verify that triggering an archive/restore action successfully calls the PUT /api/creator/update-quest-canvas endpoint with the correctly modified canvas_metadata.

    • End-to-End (E2E) / QA:

      • Flow 1 (Archive): Right-click a node -> Select "Archive" -> Confirm the node disappears from the canvas -> Open the "View Archived" modal -> Confirm the node appears in the modal.

      • Flow 2 (Restore): From the "View Archived" modal -> Click "Restore" on a node -> Confirm the modal closes or updates -> Confirm the node reappears on the canvas.

      • Flow 3 (Exclusion): Archive a node -> View the quest as a learner -> Confirm the archived node's content is not visible.

      • Flow 4 (Persistence): Archive a node -> Refresh the page -> Confirm the node remains archived.

  • Known Limitations

    • The feature does not automatically handle orphaned edges when a node is archived. The edges remain in the canvas_metadata and will reappear if the node is restored. A cleanup mechanism could be a future enhancement.

7. Maintenance & Support

Troubleshooting

  • Node does not disappear after archiving:

    1. Check the browser's developer console for JavaScript errors during the state update.

    2. Verify that the ArchivedNodeHider.tsx component is correctly wrapping the canvas renderer.

    3. Check the network tab to see if the PUT request to update-quest-canvas is failing.

  • Archived node does not reappear on page refresh (state is lost):

    1. This indicates a failure to persist the data. Check the network tab for a failed PUT request.

    2. Inspect the quests table in Supabase to see if the canvas_metadata column was updated with the archived: true flag.

Changelog

  • 1.0 - Approved, Feature implemented and shipped, 2026-05-21

    • Initial implementation of archive/restore functionality.

    • Includes ArchivedNodeHider and ArchivedNodesModal components.

Written by Uriel Last updated June 29, 2026
Was this article helpful?