IPC Bridge & Contracts

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• apps/desktop/src/App.tsx
• apps/desktop/src-tauri/Cargo.toml
• apps/desktop/src/lib/library.ts
• CHANGELOG.md

The IPC Bridge & Contracts system manages communication between the React-based frontend and the Rust-based core. This bridge uses Tauri v2 to provide a fully typed interface that prevents contract drift between the UI and the backend logic. It enables the desktop shell to perform performance-critical tasks like audio scanning, fingerprinting, and SQLite operations while maintaining a responsive user interface.

Sources: README.md:214-233, apps/desktop/src-tauri/Cargo.toml:22-30

Architecture and Data Flow

The architecture follows a strictly decoupled pattern where the frontend sends typed commands and listens for asynchronous events. The Rust core handles all heavy lifting, including database interactions and audio analysis, while the IPC bridge acts as the synchronization layer.

The diagram shows the request-response cycle and the asynchronous event stream used for long-running tasks like library scanning.
Sources: README.md:214-233, apps/desktop/src/App.tsx:501-561

Core Components

• Tauri v2 Shell: Provides the underlying IPC mechanism and native window management.
• Typed Contracts: Code-generated JSON contracts ensure that data structures in TypeScript match those in Rust.
• Event Listeners: Specific hooks in the frontend that subscribe to backend progress updates (e.g., scan progress or analysis status).

Sources: README.md:214-233, CHANGELOG.md:144-154

Command Implementation

Commands are defined in Rust and exposed to the frontend as asynchronous functions. These commands handle parameters such as folder paths, filter criteria, and track IDs.

Command	Parameters	Description
scan_folder	path: String, recursive: bool	Initiates a recursive scan of a directory for audio files.
list_tracks	filters: ListTracksFilters, sortBy: String, sortDir: String	Retrieves a filtered and sorted list of tracks from SQLite.
get_artwork	trackId: String	Resolves a cached artwork hash to a data: URL for UI display.
analyze_library	options: AnalysisOptions	Starts the local ONNX-based analysis pipeline for BPM and Key.
find_similar_tracks	trackId: String, limit: i32	Returns compatibility-scored tracks based on BPM and Camelot key.

Sources: apps/desktop/src/App.tsx:28-56, CHANGELOG.md:10-25, apps/desktop/src-tauri/Cargo.toml:35-37

Event System and Progress Tracking

For operations that take significant time, the IPC bridge uses an event-based system. The backend emits progress payloads that the frontend consumes to update progress bars and status messages.

This sequence shows how the frontend remains reactive during a library scan by receiving incremental updates via the bridge.
Sources: apps/desktop/src/App.tsx:501-521, CHANGELOG.md:209-216

Payload Structures

Events carry specific data models to ensure the UI can display precise information:

• ScanProgressEvent: Contains scannedFiles, totalFiles, and the currentPath currently being processed.
• AnalysisProgressEvent: Includes processed, total, and the filePath of the track undergoing ONNX inference.
• EnrichmentProgressEvent: Reports the status and count of metadata lookups from external providers like MusicBrainz.

Sources: apps/desktop/src/App.tsx:501-561, CHANGELOG.md:43-55

Type Safety and Contract Drift

To prevent runtime errors, the project enforces strict typing across the IPC boundary. The packages/shared directory contains the TypeScript definitions that mirror Rust structs.

// apps/desktop/src/lib/library.ts
export function normalizeFilters(
  filters: ListTracksFilters | undefined
): ListTracksFilters | undefined {
  if (!filters) return undefined;
  // Validates filter values before sending across IPC
  const normalized: ListTracksFilters = {};
  if (filters.bpmMin != null && Number.isFinite(filters.bpmMin)) {
    normalized.bpmMin = filters.bpmMin;
  }
  return Object.keys(normalized).length > 0 ? normalized : undefined;
}

Sources: apps/desktop/src/lib/library.ts:80-94, CHANGELOG.md:185-195

The bridge implementation includes:

1. CamelCase Conversion: Automatically handles the transition between Rust's snake_case and TypeScript's camelCase during serialization.
2. Constraint Validation: The UI validates inputs (like BPM ranges) before invocation to avoid unnecessary IPC overhead or backend errors.
3. CI Gating: Automated tests in crates/core/tests and packages/shared verify that the contract remains stable.

Sources: CHANGELOG.md:185-200, README.md:224-230

Conclusion

The IPC Bridge & Contracts system is the vital link that allows DJ Assistant to combine a high-performance Rust backend with a modern React frontend. By using Tauri v2 and typed contracts, the system ensures that complex operations like audio analysis and database queries are performed safely and efficiently without compromising UI responsiveness or type safety.