Structure Session Cache

Relevant source files

The following files were used as context for generating this wiki page:

• apps/web/src/features/structure-editor/lib/structure-session.ts
• apps/web/src/server/chem/structure-store.ts
• apps/web/tests/load-structure-draft.test.ts
• apps/web/src/app/page.tsx
• chemd-v0.1-architecture.md

The Structure Session Cache is a dual-layer persistence system designed to maintain the state of chemical structures during editing sessions within the cheMD platform. It ensures that complex molecular data, such as Molfiles—which contain coordinate data not typically stored in the Markdown-based SMILES strings—is preserved across browser refreshes and asynchronous API calls.

This system bridges the gap between the semantic Markdown document (the source of truth) and specialized graphical editors like Ketcher. By caching drafts both in the browser's localStorage and on a server-side store, the system prevents data loss during the transition between the text editor and the structure dialog.

Architecture and Components

The caching system operates across the client-side UI and the server-side API, utilizing unique identifiers to isolate data between different documents and users.

Component Overview

Component	Responsibility
Session Manager	Generates and retrieves unique sessionId values to isolate concurrent editing sessions.
Local Draft Store	Manages browser-based persistence using localStorage.
Structure Cache API	Provides server-side persistence via /api/chem/structure.
Load Logic	Orchestrates the fallback sequence when retrieving a structure for editing.

Sources: apps/web/src/app/page.tsx:75-76, chemd-v0.1-architecture.md:38-42, apps/web/tests/load-structure-draft.test.ts:6-10

Session Identification

The system identifies unique editing contexts using a combination of documentId, blockId, and sessionId.

• documentId: Derived from the document frontmatter.
• blockId: The unique ID of the molecule block (e.g., #mol-main).
• sessionId: A client-side identifier retrieved via getStructureSessionId(), typically persisted in localStorage under the key chemd:structure-session-id.

Sources: apps/web/src/app/page.tsx:75, apps/web/src/app/page.tsx:219-224

Retrieval Strategy (loadStructureDraft)

When a user initiates an edit on a molecule block, the system executes a tiered retrieval strategy. The primary goal is to find the most "feature-rich" version of the structure (one containing coordinates) that matches the current SMILES string in the Markdown source.

Retrieval Logic Flow

This diagram illustrates the fallback sequence for structure retrieval, prioritizing local browser state over server state and Markdown source.

Staleness Validation

A critical feature of the cache is the staleness check. Each cached entry includes a sourceSmiles field. If the SMILES string in the current Markdown editor has been changed manually since the last graphical edit, the cache is considered stale and is purged to prevent inconsistent state rehydration.

Sources: apps/web/tests/load-structure-draft.test.ts:34-45, apps/web/src/app/page.tsx:165-175

Data Model and Persistence

The cache stores an object that combines the structural identity with its graphical representation metadata.

Data Fields

Field	Type	Description
smiles	string	The simplified molecular input line entry system string.
molfile	string (optional)	The high-fidelity connection table including 2D/3D coordinates.
sourceSmiles	string	The exact SMILES string from the Markdown file at the time of the last save.
updatedAt	string (ISO)	Timestamp used to manage cache eviction or sorting.

Sources: apps/web/tests/load-structure-draft.test.ts:10-15, apps/web/src/app/page.tsx:238-243

Storage Sequence

The saving process synchronizes the local editor state with both the Markdown source and the persistent cache.

The sequence shows how a successful structure edit triggers updates across three distinct layers: the server API, the local browser cache, and the underlying Markdown document.

Sources: apps/web/src/app/page.tsx:216-249

API Endpoints

The structure session cache is supported by two primary internal API routes:

1. GET /api/chem/structure:

   • Parameters: documentId, blockId, sessionId.
   • Purpose: Fetches saved structure data (including Molfiles) from the server-side store.
   • Response: Returns { found: true, structure: { ... } } or { found: false }.

2. POST /api/chem/structure/save:

   • Body: documentId, blockId, sessionId, smiles, molfile.
   • Purpose: Persists the current editor state to the server-side cache.

Sources: apps/web/tests/load-structure-draft.test.ts:63-65, apps/web/src/app/page.tsx:219-224

Summary

The Structure Session Cache provides a robust mechanism for maintaining complex chemical data within a lightweight Markdown environment. By leveraging session-specific identifiers and validating cache integrity against the source text, cheMD ensures that users can transition seamlessly between text-based authoring and coordinate-aware graphical editing without data loss or synchronization errors.