constellation-analyzer/docs/WORKSPACE_PERSISTENCE.md

Workspace Persistence Architecture

Overview

The workspace manager now functions as a persistent document library. Documents are stored permanently in localStorage and remain available even after their tabs are closed.

Key Concepts

Document States

1. Created Documents: All documents created, imported, or opened are stored persistently in localStorage
2. Open Documents: Documents with active tabs (tracked in documentOrder)
3. Closed Documents: Documents stored in localStorage but without active tabs

Data Structure

// Workspace State (saved to localStorage)
{
  workspaceId: string;
  workspaceName: string;
  documentOrder: string[];          // IDs of documents with open tabs
  activeDocumentId: string | null;  // Currently visible document
  settings: WorkspaceSettings;
}

// Document Metadata (lightweight, one per document)
{
  id: string;
  title: string;
  isDirty: boolean;
  lastModified: string;
  viewport?: { x, y, zoom };       // Persisted viewport state
}

// In-Memory State
{
  documents: Map<string, ConstellationDocument>;     // Loaded documents (performance optimization)
  documentMetadata: Map<string, DocumentMetadata>;   // All document metadata
}

User Flows

Creating a Document

1. User clicks "New Document"
2. Document is created and saved to localStorage
3. Document ID is added to documentOrder (opens as tab)
4. Document metadata is added to documentMetadata
5. Document is loaded into memory (documents Map)

Closing a Tab

1. User closes a document tab (X button)
2. closeDocument() is called
3. Document ID is removed from documentOrder (tab disappears)
4. Document remains in localStorage (persistent storage)
5. Document metadata remains in documentMetadata
6. Document is unloaded from memory (performance optimization)

Opening a Closed Document

1. User opens Document Manager
2. All documents from documentMetadata are displayed (including closed ones)
3. Closed documents are visually indicated (no "Open" badge)
4. User clicks on a closed document
5. switchToDocument() is called
6. Document is loaded from localStorage into memory
7. Document ID is added back to documentOrder (tab appears)
8. Document becomes active

Deleting a Document

1. User clicks Delete in Document Manager
2. Confirmation dialog appears
3. If confirmed, deleteDocument() is called
4. Document is removed from localStorage (permanent deletion)
5. Document is removed from documentOrder (if open)
6. Document metadata is removed from documentMetadata
7. Document is unloaded from memory

Implementation Details

Key Functions

closeDocument(documentId)

• Removes from documentOrder (closes tab)
• Keeps in localStorage (persistent)
• Checks for unsaved changes before closing

switchToDocument(documentId)

• Loads document from localStorage if not in memory
• Adds to documentOrder if not already there (reopens tab)
• Sets as activeDocumentId

deleteDocument(documentId)

• Permanently removes from localStorage
• Removes from documentOrder
• Removes from documentMetadata
• Requires confirmation

Document Manager Display

• Shows all documents from documentMetadata (not just documentOrder)
• Visual indicators:
  • Blue border + "Open" badge: Document has an active tab
  • Orange dot: Document has unsaved changes
  • Search: Filters across all documents
• Footer shows: "X documents in workspace • Y open"

Performance Optimizations

• Lazy Loading: Documents are only loaded into memory when needed
• Unload: Closed documents are removed from memory (but stay in storage)
• Viewport Persistence: Each document's viewport state is saved and restored

History Management

• History stacks are per-document but not persisted to localStorage
• History is reset when a document is closed and reopened
• This is intentional to avoid localStorage bloat

Storage Keys

// Workspace state
'constellation:workspace:v1'

// Individual document
'constellation:document:v1:{documentId}'

// Document metadata
'constellation:meta:v1:{documentId}'

Migration Notes

• Old single-document format is automatically migrated on first load
• Migration creates a workspace with the legacy document as the first document
• Migration is one-way (cannot downgrade)

Future Enhancements

Potential improvements for future versions:

1. Recent Documents List: Show recently accessed documents separately
2. Favorites: Star/pin frequently used documents
3. Document Tags: Categorize documents with user-defined tags
4. Trash/Archive: Soft delete with recovery option
5. Cloud Sync: Synchronize workspace across devices
6. History Persistence: Optionally save undo/redo stacks (with size limits)