systems frontend workflow

Frontend workflow

Active contributors: Douwe de Vries

Purpose

The frontend workflow manages the three-step app, async request lifecycle, mapping selections, normalization config, saved-work flows, and result review state. It presents one UI while switching transport implementation at the service boundary.

Directory layout

frontend/src/
├── App.tsx
├── hooks/
├── components/
├── services/
├── features/
├── types/
└── config/

Key abstractions

Name	File	Description
useComparisonWorkflow	frontend/src/hooks/useComparisonWorkflow.ts	Top-level hook that composes lifecycle, comparison, persistence, and navigation actions.
workflowReducer	frontend/src/hooks/useComparisonWorkflow.reducer.ts	State machine for sessions, files, selections, results, snapshots, notices, and errors.
useWorkflowComparisonActions	frontend/src/hooks/useWorkflowComparisonActions.ts	File load, compare, and auto-pair actions.
useWorkflowPersistenceActions	frontend/src/hooks/useWorkflowPersistenceActions.ts	Export, pair-order, and snapshot actions.
MappingConfig	frontend/src/components/MappingConfig.tsx	Mapping, normalization, pair-order, and compare UI.
ResultsTable	frontend/src/components/ResultsTable.tsx	Searchable, sortable, expandable, chunk-rendered results table.

How it works

graph TD
    App[frontend/src/App.tsx] --> Hook[useComparisonWorkflow]
    Hook --> Reducer[workflowReducer]
    Hook --> CompareActions[useWorkflowComparisonActions]
    Hook --> PersistActions[useWorkflowPersistenceActions]
    Hook --> Navigation[useWorkflowNavigation]
    CompareActions --> Service[frontend/src/services/tauri.ts]
    PersistActions --> Service

Loading

The workflow uses generation and mutation tokens to ignore stale responses. Loading a file invalidates older comparisons; loading pair-order invalidates older workflow state; loading a snapshot switches results into read-only mode.

Integration points

frontend/src/services/tauri.ts is the runtime boundary. Component props use types from frontend/src/types/api.ts and frontend/src/types/ui.ts. Result rendering is delegated to frontend/src/features/results/presentation.ts and search text to frontend/src/features/results/search.ts.

Entry points for modification

For new state transitions, update frontend/src/hooks/useComparisonWorkflow.reducer.ts first. For new backend operations, add a service function in frontend/src/services/tauri.ts and update types in frontend/src/types/api.ts. For UI sections, add tests next to the component or hook.

Key source files

File	Purpose
frontend/src/App.tsx	Step shell.
frontend/src/hooks/useComparisonWorkflow.ts	Workflow composition.
frontend/src/hooks/useComparisonWorkflow.reducer.ts	State transitions.
frontend/src/components/MappingConfig.tsx	Configuration step UI.
frontend/src/components/ResultsTable.tsx	Detailed result UI.