how to contribute patterns and conventions

Patterns and conventions

CSV Align favors shared Rust workflows, explicit request/response contracts, and transport parity. The same user action should behave the same through browser HTTP and desktop Tauri.

Shared workflow first

Browser handlers in src/api/handlers.rs and desktop commands in src-tauri/src/commands.rs should call functions from src/backend/workflow.rs instead of duplicating business logic. This keeps CSV loading, comparison execution, pair-order files, snapshots, and export behavior consistent.

Typed contracts

Rust request types live in src/backend/requests.rs. Rust response types live in src/presentation/responses.rs. Frontend equivalents live in frontend/src/types/api.ts. When one side changes, update the other side and add contract coverage in tests/response_contracts.rs or frontend service tests.

Error handling

src/backend/error.rs maps CsvAlignError to an HTTP/Tauri-serializable body with a stable code and human-readable error. UI code reads those through frontend/src/services/http.ts, frontend/src/services/tauri.ts, and frontend/src/hooks/useComparisonWorkflow.reducer.ts.

Session safety

src/backend/store.rs uses an in-memory SessionStore. src/backend/workflow.rs checks data_revision and Arc::ptr_eq before storing comparison results, so a comparison cannot overwrite a newer file selection.

Frontend async safety

frontend/src/hooks/useComparisonWorkflow.ts uses workflow generation and mutation counters. Long-running file, compare, pair-order, and snapshot requests dispatch only when their token still matches the current workflow.

Transport parity

Every frontend invoke in frontend/src/services/tauri.ts must have a command in src-tauri/src/commands.rs and registration in src-tauri/src/main.rs. Every browser operation should point to a route built from frontend/src/services/apiRoutes.ts and registered in src/api/app.rs.

Logging

Production Rust code should use tracing macros. src/main.rs, src/api/handlers.rs, and src-tauri/src/main.rs initialize or instrument the main runtime paths.

For command details, see transport parity. For validation commands, see getting started.