systems persistence and export

Persistence and export

Active contributors: Douwe de Vries

Purpose

Persistence lets users save repeat setup work as pair-order files and save completed comparisons as snapshots. Export writes reviewed results as CSV, while the frontend also builds standalone HTML exports.

Directory layout

src/backend/
├── pair_order.rs
├── comparison_snapshot.rs
└── persistence/v1/mod.rs
src/data/export.rs
frontend/src/features/results/
├── htmlExport.ts
├── htmlExportTemplate.ts
└── htmlExportTheme.ts

Key abstractions

Name	File	Description
PAIR_ORDER_FILE_VERSION	src/backend/pair_order.rs	Current pair-order file version.
SnapshotV1	src/backend/persistence/v1/mod.rs	Versioned snapshot data model.
SNAPSHOT_VERSION	src/backend/persistence/v1/mod.rs	Current snapshot version, currently 2.
export_results_to_bytes	src/data/export.rs	Builds CSV export bytes from results and optional config.
buildResultsHtmlDocument	frontend/src/features/results/htmlExport.ts	Builds a standalone HTML export document.

How it works

Pair-order files store selected key and comparison columns with the source headers. Loading validates the version, header multiset, selected labels, and paired counts against the current session.

Snapshots store file metadata, selection, mappings, normalization, results, and summary. Loading validates metadata, virtual labels, mapping coverage, and recomputed summary before hydrating the session into read-only results mode.

graph LR
    Session[SessionData] --> PairOrder[pair-order JSON]
    Session --> Snapshot[comparison snapshot JSON]
    Results[RowComparisonResult] --> CSV[src/data/export.rs]
    Results --> HTML[frontend HTML export]

Loading

Integration points

HTTP handlers in src/api/handlers.rs return pair-order, snapshot, and CSV export attachments. Tauri commands in src-tauri/src/commands.rs use native save/open dialogs. Frontend persistence actions live in frontend/src/hooks/useWorkflowPersistenceActions.ts.

Entry points for modification

Change pair-order behavior in src/backend/pair_order.rs and tests under tests/pair_order_persistence_integration.rs. Change snapshots in src/backend/persistence/v1/mod.rs, then update snapshot integration, router, and Tauri tests. Change CSV export in src/data/export.rs; change HTML export in frontend/src/features/results/htmlExport.ts and htmlExportTemplate.ts.

Key source files

File	Purpose
src/backend/pair_order.rs	Pair-order save/load validation and serialization.
src/backend/comparison_snapshot.rs	Snapshot workflow preparation and application.
src/backend/persistence/v1/mod.rs	Snapshot schema and validation.
src/data/export.rs	CSV export layout and records.
frontend/src/features/results/htmlExport.ts	HTML export model assembly.