systems

Systems

Active contributors: Douwe de Vries

Purpose

This section maps the internal systems that make CSV Align work across the shared Rust backend, Axum web app, Tauri desktop shell, and React frontend. Use it when you need to find the right subsystem before changing CSV loading, comparison behavior, workflow orchestration, UI state, or transport contracts.

Directory layout

Page	Scope
CSV loading	File-size checks, CSV decoding, delimiter detection, parse errors, column metadata, and virtual JSON fields.
Comparison engine	Row-key matching, flexible keys, duplicate and missing row categories, value normalization, and summaries.
Backend workflow	Session state, shared backend workflows, validation, stale writeback protection, persistence, and export.
Frontend workflow	React step flow, reducer actions, file selection, configuration, results presentation, search, and export hooks.
Transport parity	Browser HTTP routes, Tauri command names, backend registration, parity tests, and change checklist.

Key abstractions

Abstraction	Primary paths	Notes
Session	src/backend/session.rs, src/backend/store.rs	In-memory workspace for loaded files, detected columns, mappings, comparison results, and the current config.
Loaded CSV	src/data/types.rs, src/data/csv_loader.rs, src/data/json_fields.rs	Physical headers, rows, detected column types, and selectable virtual JSON labels.
Comparison config	src/backend/requests.rs, src/backend/validation.rs, src/data/types.rs	Validated row keys, comparison columns, mappings, and cleanup rules.
Comparison result	src/comparison/engine.rs, src/data/types.rs, src/presentation/responses.rs	Match, mismatch, missing, unkeyed, and duplicate row outcomes plus summary counts.
Workflow state	frontend/src/hooks/useComparisonWorkflow.ts, frontend/src/hooks/useComparisonWorkflow.reducer.ts	React state for the select, configure, and results steps.
Transport contract	frontend/src/services/apiRoutes.ts, frontend/src/services/tauriCommands.ts, src/api/app.rs, src-tauri/src/main.rs	Names that must stay aligned across browser, desktop, and tests.

How it works

graph TD
    User[User] --> Frontend[React workflow]
    Frontend --> Transport[Transport switch]
    Transport --> Browser[Axum HTTP routes]
    Transport --> Desktop[Tauri commands]
    Browser --> Backend[Shared backend workflows]
    Desktop --> Backend
    Backend --> Loading[CSV loading]
    Backend --> Store[Session store]
    Backend --> Compare[Comparison engine]
    Backend --> Save[Persistence and export]
    Compare --> Response[Presentation responses]
    Response --> Frontend

Loading

The frontend starts in frontend/src/App.tsx, keeps UI state in frontend/src/hooks/useComparisonWorkflow.ts, and calls frontend/src/services/tauri.ts. Browser mode routes to src/api/app.rs and src/api/handlers.rs. Desktop mode invokes commands from src-tauri/src/commands.rs. Both runtimes call shared workflows in src/backend/workflow.rs, which in turn call the CSV data layer and comparison engine.

Integration points

• Overview gives the application-level summary.
• Architecture shows the shared backend and two app shells.
• Saved work describes pair-order files and comparison snapshots.
• Flexible row-key matching describes the user-facing flexible matching feature.
• API is the contract surface linked from transport parity.
• Testing is the verification entry point for changes.

Entry points for modification

Change type	Start here	Then check
CSV parse behavior or file limits	CSV loading	src/backend/workflow.rs, src/data/csv_loader.rs, frontend/src/services/tauri.ts
Row matching or value cleanup	Comparison engine	src/comparison/engine.rs, src/comparison/rows.rs, src/comparison/value_compare.rs
Session lifecycle, validation, save, or export	Backend workflow	src/backend/workflow.rs, src/backend/store.rs, src/backend/validation.rs
UI state, navigation, filters, or export buttons	Frontend workflow	frontend/src/hooks/useComparisonWorkflow.ts, frontend/src/components/app/ResultsStep.tsx
New frontend API operation	Transport parity	frontend/src/services/apiRoutes.ts, frontend/src/services/tauriCommands.ts, src/api/app.rs, src-tauri/src/main.rs

Key source files

File	Purpose
src/backend/workflow.rs	Shared workflow orchestration for loading, mapping, comparison, persistence, and export.
src/backend/store.rs	Session lifecycle, idle eviction, and memory budget enforcement.
src/data/csv_loader.rs	CSV byte decoding, delimiter detection, header validation, row parsing, and column type detection.
src/data/json_fields.rs	Virtual JSON field discovery and extraction.
src/comparison/engine.rs	Row grouping, exact and flexible matching, result generation, and summary counts.
frontend/src/App.tsx	Top-level select, configure, and results workflow.
frontend/src/hooks/useComparisonWorkflow.ts	Main frontend workflow hook.
frontend/src/services/tauri.ts	Browser and Tauri transport switch.
src/api/app.rs	HTTP route constants and Axum router registration.
src-tauri/src/main.rs	Tauri command registration.