systems frontend workflow

Frontend workflow

Active contributors: Douwe de Vries

Purpose

The frontend workflow coordinates the user-facing select, configure, and results steps. It keeps React state aligned with backend sessions, blocks stale async responses, renders physical and virtual columns for selection, submits comparison requests, and turns backend results into searchable, sortable, exportable view models.

Directory layout

Area	Paths	Responsibility
Top-level app	frontend/src/App.tsx	Renders the header, progress steps, error and loading banners, and the active workflow step.
Main hook	frontend/src/hooks/useComparisonWorkflow.ts	Composes reducer state, session lifecycle, comparison actions, persistence actions, and navigation.
Reducer	frontend/src/hooks/useComparisonWorkflow.reducer.ts	Defines workflow state, actions, default state, compare request payloads, and state transitions.
Session lifecycle	frontend/src/hooks/useWorkflowSessionLifecycle.ts	Creates and deletes backend sessions and resets the workflow.
Comparison actions	frontend/src/hooks/useWorkflowComparisonActions.ts	Loads files, runs comparisons, and requests auto-pair mapping suggestions.
Persistence actions	frontend/src/hooks/useWorkflowPersistenceActions.ts	Exports CSV and HTML, saves or loads pair-order files, and saves or loads snapshots.
Navigation	frontend/src/hooks/useWorkflowNavigation.ts	Computes unlocked steps and controls step changes.
Step components	frontend/src/components/app/FileSelectionStep.tsx, frontend/src/components/app/ConfigurationStep.tsx, frontend/src/components/app/ResultsStep.tsx	Render the three workflow screens.
Results presentation	frontend/src/features/results/presentation.ts, frontend/src/features/results/search.ts, frontend/src/components/ResultsTable.tsx	Build rows, badges, filters, summary view models, search text, sorting, and expandable details.
Transport	frontend/src/services/tauri.ts	Switches browser HTTP calls and Tauri invokes.

Key abstractions

Abstraction	Defined in	Notes
WorkflowState	frontend/src/hooks/useComparisonWorkflow.reducer.ts	Combines app state, current step, mapping selection, and normalization config.
AppState	frontend/src/types/api.ts	Session id, loaded files, mappings, results, summary, read-only snapshot flag, filter, error, and loading state.
AppStep	frontend/src/types/ui.ts	One of select, configure, or results.
MappingSelectionState	frontend/src/types/ui.ts	Selected key columns and comparison columns for File A and File B.
ComparisonNormalizationConfig	frontend/src/types/api.ts	Frontend shape for backend normalization options.
ResultRowViewModel	frontend/src/features/results/presentation.ts	Render-ready result row with labels, values, search fields, sort values, and detail panels.
WorkflowRequestToken	frontend/src/hooks/useComparisonWorkflow.ts	Session, generation, and mutation guard used to ignore stale async responses.

How it works

stateDiagram-v2
    [*] --> Select: createSession()
    Select --> Select: load File A or File B
    Select --> Configure: both files loaded
    Configure --> Configure: edit keys, pairs, normalization, pair-order
    Configure --> Results: compareSucceeded
    Select --> Results: snapshotLoaded
    Results --> Configure: back, unless snapshot read-only
    Results --> Select: resetWorkflow

Loading

sequenceDiagram
    participant App as frontend/src/App.tsx
    participant Hook as useComparisonWorkflow()
    participant Reducer as workflowReducer
    participant Transport as frontend/src/services/tauri.ts
    participant Backend as Shared backend

    App->>Hook: render workflow state and handlers
    Hook->>Transport: createSession()
    Transport->>Backend: browser route or Tauri command
    Backend-->>Hook: session id
    Hook->>Reducer: sessionCreated
    App->>Hook: handleFileSelection()
    Hook->>Transport: loadFile()
    Backend-->>Hook: FileLoadResponse
    Hook->>Reducer: fileLoaded
    App->>Hook: handleCompare()
    Hook->>Transport: compareFiles()
    Backend-->>Hook: CompareResponse
    Hook->>Reducer: compareSucceeded

Loading

frontend/src/hooks/useComparisonWorkflow.ts owns async request guards:

• workflowGenerationRef changes when the whole workflow resets.
• workflowMutationRef changes when an operation invalidates existing workflow data.
• currentSessionIdRef tracks the active backend session.

Every async handler gets a token from beginWorkflowRequest or invalidateWorkflowRequests. Responses are applied only when isCurrentWorkflowRequest still passes.

Reducer and actions

workflowReducer in frontend/src/hooks/useComparisonWorkflow.reducer.ts is the single place where workflow state transitions are applied.

Action	State effect
sessionCreated	Stores the backend session id.
fileLoaded	Stores File A or File B metadata, clears mappings and results, resets normalization and selection, and moves to configure when both files exist.
compareSucceeded	Stores results and summary, clears errors, and moves to results.
snapshotLoaded	Replaces file metadata, selection, normalization, mappings, results, and summary, then marks the workflow read-only.
pairOrderLoaded	Applies saved key and comparison selections and returns to configure.
autoPairSucceeded	Applies generated mapping suggestions and selected comparison pairs.
filterChanged	Updates the active result filter.
mappingSelectionChanged	Stores the current key and comparison selections.
normalizationConfigChanged	Stores cleanup rule changes.
stepChanged	Updates the active step after navigation checks.
resetWorkflow	Restores the initial select-step state.

Loaded comparison snapshots are read-only. SNAPSHOT_READ_ONLY_ERROR blocks follow-on file, configure, compare, pair-order, and back-navigation actions that would mutate the loaded result.

File selection components

frontend/src/components/app/FileSelectionStep.tsx renders two FileSelector instances and a saved-result load action.

frontend/src/components/FileSelector.tsx:

• Accepts files with a .csv extension.
• Supports browser drag-and-drop and file picker selection.
• Listens for Tauri drag/drop events for visual feedback.
• Rejects raw desktop paths and tells the user to use the file picker.
• Displays loaded row count, column count, headers, and detected column types from the backend response.

frontend/src/services/tauri.ts sends browser uploads through multipart HTTP and sends desktop file bytes through load_csv_bytes.

Configuration components

frontend/src/components/app/ConfigurationStep.tsx shows both loaded files and delegates selection to frontend/src/components/MappingConfig.tsx.

frontend/src/components/MappingConfig.tsx coordinates:

• frontend/src/components/mapping-config/NormalizationPanel.tsx for cleanup rules.
• frontend/src/components/mapping-config/ColumnChipSelector.tsx for physical and virtual JSON field selection.
• frontend/src/components/mapping-config/PairPreview.tsx for pair-order preview, auto-pair buttons, and pair-order save or load.

Key behavior:

• Empty key selection defaults to the first header on each file when comparing.
• Comparison columns must have the same count before compare is enabled.
• Key column counts must match unless flexible row-key matching is enabled.
• Manual mappings are built positionally from selected comparison columns.
• Auto-pair requires explicit matching key counts before it asks the backend for mapping suggestions.

Results components

frontend/src/components/app/ResultsStep.tsx renders:

• frontend/src/components/SummaryStats.tsx for match rate, comparable outcome counts, ignored-row banners, and duplicate-key banners.
• frontend/src/components/FilterBar.tsx for result buckets and CSV or HTML export buttons.
• frontend/src/components/ResultsTable.tsx for detailed rows, search, sorting, and expandable differences or inspections.

frontend/src/features/results/presentation.ts converts backend ResultResponse values into ResultRowViewModel objects. It assigns labels, badge tones, filter buckets, key text, value cells, difference details, inspection panels, summary cards, and sort values.

frontend/src/features/results/search.ts builds normalized search text for all fields, result type, key, File A values, and File B values. frontend/src/components/ResultsTable.tsx uses deferred search input and local sorting to keep large result lists responsive.

Result export hooks

frontend/src/hooks/useWorkflowPersistenceActions.ts centralizes export and persistence handlers.

Handler	Browser behavior	Tauri behavior
handleExportCsv	Downloads blob returned by exportResults.	Opens a save dialog in the Tauri command.
handleExportHtml	Builds HTML in frontend/src/features/results/htmlExport.ts and downloads a blob.	Builds HTML in the frontend, then asks Tauri to save it.
handleSaveComparisonSnapshot	Downloads snapshot JSON from backend.	Opens a save dialog in the Tauri command.
handleLoadComparisonSnapshot	Reads selected JSON file text and posts it to the backend.	Opens a pick dialog in the Tauri command.
handleSavePairOrder	Downloads pair-order text from backend.	Opens a save dialog in the Tauri command.
handleLoadPairOrder	Reads selected pair-order file text and posts it to the backend.	Opens a pick dialog in the Tauri command.

Integration points

• CSV loading explains the file metadata that populates File A and File B.
• Backend workflow explains the backend session state mirrored by the reducer.
• Comparison engine explains the result categories that frontend presentation maps to labels.
• Transport parity lists the browser routes and Tauri command names used by frontend/src/services/tauri.ts.
• Saved work explains pair-order files and snapshots from the user-facing perspective.
• Testing lists frontend validation commands.

Entry points for modification

Need	Change first	Also check
Add a workflow state transition	frontend/src/hooks/useComparisonWorkflow.reducer.ts	Hook tests under frontend/src/hooks/.
Change async behavior or race protection	frontend/src/hooks/useComparisonWorkflow.ts	All action hooks using request tokens.
Change session reset or creation	frontend/src/hooks/useWorkflowSessionLifecycle.ts	Backend session delete behavior in frontend/src/services/tauri.ts.
Change file selection UX	frontend/src/components/app/FileSelectionStep.tsx, frontend/src/components/FileSelector.tsx	CSV loading limits in frontend/src/services/tauri.ts.
Change configuration UI	frontend/src/components/MappingConfig.tsx	Backend validation in src/backend/validation.rs.
Change result labels or filters	frontend/src/features/results/presentation.ts	frontend/src/components/FilterBar.tsx, frontend/src/components/ResultsTable.tsx.
Change search fields	frontend/src/features/results/search.ts	frontend/src/components/results/SearchFieldPicker.tsx.
Change exports	frontend/src/hooks/useWorkflowPersistenceActions.ts, frontend/src/features/results/htmlExport.ts	Backend export and Tauri save commands.

Key source files

File	Purpose
frontend/src/App.tsx	Top-level workflow rendering and handler wiring.
frontend/src/hooks/useComparisonWorkflow.ts	Main workflow hook and stale async request guards.
frontend/src/hooks/useComparisonWorkflow.reducer.ts	State shape, reducer actions, defaults, and compare request builder.
frontend/src/hooks/useWorkflowComparisonActions.ts	Load, compare, and auto-pair actions.
frontend/src/hooks/useWorkflowPersistenceActions.ts	Export, pair-order, and snapshot actions.
frontend/src/hooks/useWorkflowSessionLifecycle.ts	Session creation, deletion, and reset.
frontend/src/hooks/useWorkflowNavigation.ts	Step unlocking and navigation.
frontend/src/components/app/FileSelectionStep.tsx	File selection step.
frontend/src/components/app/ConfigurationStep.tsx	Configuration step wrapper.
frontend/src/components/MappingConfig.tsx	Key, comparison, normalization, auto-pair, and pair-order UI.
frontend/src/components/app/ResultsStep.tsx	Results step wrapper.
frontend/src/features/results/presentation.ts	Result and summary view-model construction.
frontend/src/features/results/search.ts	Search field definitions and normalized search text.
frontend/src/components/ResultsTable.tsx	Results search, sorting, expandable details, and table rendering.
frontend/src/services/tauri.ts	Browser and desktop transport switch.