overview architecture

Architecture

CSV Align has one shared Rust backend used by two runtimes: an Axum local web server and a Tauri desktop shell. The frontend calls HTTP in browser mode and Tauri commands in desktop mode through one transport switch.

Runtime shape

graph LR
    User[User] --> UI[React UI]
    UI -->|browser mode HTTP| API[Axum API]
    UI -->|desktop mode invoke| Tauri[Tauri commands]
    API --> Workflows[Shared backend workflows]
    Tauri --> Workflows
    Workflows --> Store[SessionStore]
    Workflows --> Data[CSV loading and JSON fields]
    Workflows --> Compare[Comparison engine]
    Workflows --> Persist[Pair-order, snapshots, export]

Loading

src/main.rs builds the Axum app from src/api/app.rs and serves frontend/dist. src-tauri/src/main.rs registers commands from src-tauri/src/commands.rs, and those commands call the same functions in src/backend/workflow.rs.

Request and data flow

sequenceDiagram
    participant UI as frontend/src
    participant Transport as frontend/src/services/tauri.ts
    participant Runtime as Axum or Tauri
    participant Workflow as src/backend/workflow.rs
    participant Store as src/backend/store.rs
    participant Engine as src/comparison/engine.rs

    UI->>Transport: load file / compare / export
    Transport->>Runtime: HTTP route or invoke command
    Runtime->>Workflow: shared workflow function
    Workflow->>Store: read or mutate session
    Workflow->>Engine: build and execute comparison plan
    Engine-->>Workflow: row results and summary
    Workflow-->>Runtime: typed response
    Runtime-->>Transport: JSON, Blob, or saved dialog outcome
    Transport-->>UI: reducer action payload

Loading

The API boundary is defined by src/api/app.rs, src/api/handlers.rs, src/backend/requests.rs, src/presentation/responses.rs, and frontend/src/types/api.ts. Keeping these files aligned is the main cross-language maintenance task.

Subsystems

Subsystem	Main files	Notes
API routing	src/api/app.rs, src/api/handlers.rs	Axum routes, upload limits, blocking workflow dispatch, response attachments.
Session store	src/backend/store.rs, src/backend/session.rs	In-memory sessions with max session, idle timeout, and total byte budget eviction.
CSV data	src/data/csv_loader.rs, src/data/json_fields.rs, src/data/types.rs	Delimiter detection, column type inference, duplicate header rejection, virtual JSON labels.
Comparison	src/comparison/engine.rs, src/comparison/rows.rs, src/comparison/value_compare.rs, src/comparison/mapping.rs	Exact/flexible key matching, normalization, row result generation, mapping suggestions.
Persistence	src/backend/pair_order.rs, src/backend/comparison_snapshot.rs, src/backend/persistence/v1/mod.rs, src/data/export.rs	Pair-order files, snapshot files, CSV export.
Frontend workflow	frontend/src/App.tsx, frontend/src/hooks/, frontend/src/components/	Step navigation, mapping UI, results UI, stale async request guards.
Desktop wrapper	src-tauri/src/main.rs, src-tauri/src/commands.rs	Native dialogs, raw IPC byte uploads, desktop saves.

Codebase snapshot

Product code is mostly Rust and TypeScript/TSX. A July 2, 2026 scan found roughly 17,493 Rust lines, 8,581 TypeScript lines, and 6,181 TSX lines, excluding process artifacts under .factory/. See by the numbers for the full snapshot.

Modification boundaries

• Add core comparison behavior in src/comparison/ and expose it through src/backend/workflow.rs.
• Add API or command fields in src/backend/requests.rs, src/presentation/responses.rs, and frontend/src/types/api.ts together.
• Add Tauri commands in both src-tauri/src/commands.rs and the tauri_commands! macro in src-tauri/src/main.rs.
• Add frontend workflow transitions in frontend/src/hooks/useComparisonWorkflow.reducer.ts before wiring components.

More details live in patterns and conventions and transport parity.