systems transport parity

Transport parity

Active contributors: Douwe de Vries

Purpose

Transport parity keeps browser mode and Tauri desktop mode aligned while both call the same shared backend workflows. The frontend transport switch, HTTP route constants, Tauri command constants, backend route registration, command registration, and tests must move together whenever a workflow operation is added, renamed, or removed.

Directory layout

Area	Paths	Responsibility
Frontend switch	frontend/src/services/tauri.ts	Chooses Tauri invoke calls when __TAURI_INTERNALS__ exists, otherwise uses browser HTTP routes.
Browser route constants	frontend/src/services/apiRoutes.ts	Defines frontend route templates and builders.
Tauri command constants	frontend/src/services/tauriCommands.ts	Defines frontend command names passed to invoke.
Axum routes	src/api/app.rs	Defines backend route constants and registers handlers in the router.
Axum handlers	src/api/handlers.rs	Calls shared backend workflows and formats JSON or attachment responses.
Tauri registration	src-tauri/src/main.rs	Registers command handlers through the tauri_commands! macro and tauri::generate_handler!.
Tauri commands	src-tauri/src/commands.rs	Implements desktop command wrappers around shared backend workflows and file dialogs.
Parity tests	tests/transport_parity_integration.rs, src-tauri/src/tests.rs	Assert frontend constants match backend route and command registration.

Key abstractions

Abstraction	Defined in	Notes
API_ROUTE_TEMPLATES	frontend/src/services/apiRoutes.ts	Browser route templates with {sessionId} and {fileLetter} placeholders.
TRANSPORT_PARITY_ROUTE_PATHS	src/api/app.rs	Backend route constants included in the route parity test.
TAURI_COMMANDS	frontend/src/services/tauriCommands.ts	Frontend command-name map for invoke.
tauri_commands!	src-tauri/src/main.rs	Single list used for Tauri command registration and test support.
REGISTERED_TAURI_COMMAND_NAMES	src-tauri/src/test_support.rs	Test-only list generated from tauri_commands!.
SessionStore	src/backend/store.rs	Shared backend state managed by both the Axum app and Tauri builder.

How it works

flowchart LR
    UI[React workflow] --> Switch[frontend/src/services/tauri.ts]
    Switch -->|isTauri false| Routes[frontend/src/services/apiRoutes.ts]
    Routes --> Fetch[fetch HTTP]
    Fetch --> Axum[src/api/app.rs]
    Axum --> Handlers[src/api/handlers.rs]
    Switch -->|isTauri true| Commands[frontend/src/services/tauriCommands.ts]
    Commands --> Invoke[Tauri invoke]
    Invoke --> Registered[src-tauri/src/main.rs]
    Registered --> TauriCommands[src-tauri/src/commands.rs]
    Handlers --> Workflow[src/backend/workflow.rs]
    TauriCommands --> Workflow

Loading

frontend/src/services/tauri.ts exports one function per frontend operation. Each function branches on isTauri:

• Browser mode calls a route builder from frontend/src/services/apiRoutes.ts and uses fetch.
• Tauri mode calls invoke with a command name from frontend/src/services/tauriCommands.ts.

Both sides call shared workflow functions in src/backend/workflow.rs. Browser handlers usually return JSON or downloadable blobs. Tauri commands use native dialogs for save and load operations where desktop UX requires a file path.

Browser routes

Operation	Frontend template in frontend/src/services/apiRoutes.ts	Backend constant in src/api/app.rs	Method
Create session	/api/sessions	CREATE_SESSION_ROUTE	POST
Delete session	/api/sessions/{sessionId}	DELETE_SESSION_ROUTE	DELETE
Load file	/api/sessions/{sessionId}/files/{fileLetter}	LOAD_CSV_ROUTE	POST
Suggest mappings	/api/sessions/{sessionId}/mappings	SUGGEST_MAPPINGS_ROUTE	POST
Compare	/api/sessions/{sessionId}/compare	COMPARE_ROUTE	POST
Export CSV	/api/sessions/{sessionId}/export	EXPORT_RESULTS_ROUTE	GET
Save pair order	/api/sessions/{sessionId}/pair-order/save	SAVE_PAIR_ORDER_ROUTE	POST
Load pair order	/api/sessions/{sessionId}/pair-order/load	LOAD_PAIR_ORDER_ROUTE	POST
Save comparison snapshot	/api/sessions/{sessionId}/comparison-snapshot/save	SAVE_COMPARISON_SNAPSHOT_ROUTE	POST
Load comparison snapshot	/api/sessions/{sessionId}/comparison-snapshot/load	LOAD_COMPARISON_SNAPSHOT_ROUTE	POST

tests/transport_parity_integration.rs reads frontend/src/services/apiRoutes.ts, extracts route templates, normalizes backend placeholder names from {session_id} and {file_letter} to frontend naming, and asserts the ordered lists match TRANSPORT_PARITY_ROUTE_PATHS.

Tauri commands

Frontend constant in frontend/src/services/tauriCommands.ts	Backend command in src-tauri/src/commands.rs	Notes
create_session	create_session	Creates a session in shared SessionStore.
delete_session	delete_session	Deletes a session, no-op for missing ids in desktop mode.
load_csv_bytes	load_csv_bytes	Loads user-selected file bytes and rejects invalid file letters.
suggest_mappings	suggest_mappings	Uses current session data when available.
compare	compare	Runs shared comparison workflow.
export_results	export_results	Opens a save dialog and writes CSV output.
export_results_html	export_results_html	Saves frontend-generated HTML through a desktop save dialog.
save_pair_order	save_pair_order	Opens a save dialog and writes pair-order text.
load_pair_order	load_pair_order	Opens a pick dialog and returns parsed pair-order selection.
save_comparison_snapshot	save_comparison_snapshot	Opens a save dialog and writes snapshot JSON.
load_comparison_snapshot	load_comparison_snapshot	Opens a pick dialog and returns snapshot results.

src-tauri/src/tests.rs reads frontend/src/services/tauriCommands.ts and compares those command strings to REGISTERED_TAURI_COMMAND_NAMES, which is generated from the tauri_commands! macro in src-tauri/src/main.rs.

export_results_html is desktop-only on the backend side. Browser mode creates and downloads an HTML blob in frontend/src/services/tauri.ts, while desktop mode needs a Tauri command so it can open a native save dialog.

Backend command and route registration

Browser registration

src/api/app.rs defines every browser route constant and registers it in build_api_router.

flowchart TD
    Constants[src/api/app.rs route constants] --> ParityList[TRANSPORT_PARITY_ROUTE_PATHS]
    Constants --> Router[build_api_router()]
    Router --> Handlers[src/api/handlers.rs]
    Handlers --> Workflow[src/backend/workflow.rs]
    ParityList --> Test[tests/transport_parity_integration.rs]

Loading

When a browser route is added, it must be present in both the route constants and TRANSPORT_PARITY_ROUTE_PATHS, then registered in build_api_router.

Tauri registration

src-tauri/src/main.rs keeps the canonical command registration list in tauri_commands!.

flowchart TD
    Macro[tauri_commands! in src-tauri/src/main.rs] --> Handler[tauri::generate_handler!]
    Macro --> Names[REGISTERED_TAURI_COMMAND_NAMES]
    Handler --> Runtime[Tauri invoke handler]
    Runtime --> Commands[src-tauri/src/commands.rs]
    Names --> Test[src-tauri/src/tests.rs]

Loading

When a Tauri command is added, it must be implemented in src-tauri/src/commands.rs, imported in src-tauri/src/main.rs, listed in tauri_commands!, and added to frontend/src/services/tauriCommands.ts.

Integration points

• Backend workflow is the shared target for both transports.
• Frontend workflow is the caller of frontend/src/services/tauri.ts.
• CSV loading covers the loadFile route and load_csv_bytes command.
• API is the broader serialized contract reference.
• Testing lists validation commands after changing routes or commands.

Entry points for modification

Need	Change first	Also check
Add a browser operation	frontend/src/services/apiRoutes.ts, src/api/app.rs, src/api/handlers.rs	tests/transport_parity_integration.rs and the corresponding frontend service function.
Add a desktop operation	frontend/src/services/tauriCommands.ts, src-tauri/src/commands.rs, src-tauri/src/main.rs	src-tauri/src/tests.rs.
Add an operation used by both modes	frontend/src/services/tauri.ts	Browser route constants, Tauri command constants, backend workflow function, and both parity tests.
Change a route path	frontend/src/services/apiRoutes.ts, src/api/app.rs	Route parity test and any API documentation.
Change a command name	frontend/src/services/tauriCommands.ts, src-tauri/src/main.rs	Tauri parity test and all invoke callers.
Change request or response shape	src/backend/requests.rs, src/presentation/responses.rs, frontend/src/types/api.ts	Both browser handlers and Tauri commands.

Modification checklist

Use this checklist before finishing any transport-facing change:

1. Add or update shared backend request and response types in src/backend/requests.rs and src/presentation/responses.rs.
2. Add or update the shared workflow in src/backend/workflow.rs.
3. Update browser route templates in frontend/src/services/apiRoutes.ts if browser mode needs the operation.
4. Update backend route constants, TRANSPORT_PARITY_ROUTE_PATHS, and build_api_router in src/api/app.rs.
5. Add or update the handler in src/api/handlers.rs.
6. Update TAURI_COMMANDS in frontend/src/services/tauriCommands.ts if desktop mode needs the operation.
7. Add or update the command in src-tauri/src/commands.rs.
8. Import and register the command through tauri_commands! in src-tauri/src/main.rs.
9. Update frontend/src/services/tauri.ts so browser and desktop behavior stay aligned.
10. Run route and command parity tests, plus the relevant frontend, backend, or Tauri validators for the changed area.

Key source files

File	Purpose
frontend/src/services/tauri.ts	Runtime transport switch and operation wrappers.
frontend/src/services/apiRoutes.ts	Browser route templates and builder functions.
frontend/src/services/tauriCommands.ts	Tauri command-name constants used by invoke.
src/api/app.rs	Backend HTTP route constants, parity route list, body limits, and Axum router registration.
src/api/handlers.rs	HTTP handlers that call shared backend workflows.
src/api/state.rs	Axum application state around shared SessionStore.
src-tauri/src/main.rs	Tauri builder, managed store, and command registration list.
src-tauri/src/commands.rs	Tauri command implementations and native dialog wrappers.
src-tauri/src/test_support.rs	Generated registered command-name list for tests.
tests/transport_parity_integration.rs	Browser route parity test.
src-tauri/src/tests.rs	Tauri command parity and desktop wrapper tests.