Desktop App & React UI
Relevant source files
The following files were used as context for generating this wiki page:
The Desktop App and React UI comprise the frontend layer of DJ Assistant, built using React 18, TypeScript, and Tailwind CSS v4. This module provides a local-first interface for DJs to manage music libraries, perform audio analysis, and prepare sets. The application runs within a Tauri v2 shell, which bridges the web-based UI with a high-performance Rust core for file system access and audio processing.
The UI focuses on non-destructive library management. It allows users to scan local folders, visualize track metadata, and perform advanced filtering and sorting via a deterministic SQLite-backed backend. It also includes specialized views for track inspection, tag health auditing, and chart snapshot visualization.
Sources: README.md:214-222, apps/desktop/package.json:18-28
System Architecture
The desktop application follows a split-process architecture. The Frontend (UI) handles user interaction and state management using React, while the Backend (Core) handles heavy lifting such as BLAKE3 fingerprinting, audio decoding, and SQLite persistence. Communication between these layers occurs via an Inter-Process Communication (IPC) bridge provided by Tauri.
The diagram shows the flow of data from user interactions in React through the IPC bridge to the Rust backend and back via events.
Sources: README.md:214-230, apps/desktop/src/App.tsx:556-620
Core UI Components
Library Management
The library view is the primary interface for track management. It renders a sortable table of tracks with metadata including BPM, Key (Camelot and Classical), Rating, and Duration.
SortHeader: A component that manages server-side sorting by triggering IPC calls with specific sort keys and directions.ArtworkThumb: Lazily loads cached cover art from the backend using theget_artworkIPC command, falling back to a placeholder icon if art is missing.LibraryFilterPanel: A dropdown interface for defining structured SQL filters, such as BPM ranges, Camelot keys, and analysis status.
Sources: apps/desktop/src/App.tsx:112-166, apps/desktop/src/App.tsx:173-346
Track Inspector
When a user selects a track, an inspector drawer opens to provide deeper insights. It utilizes the following logic:
- Similarity Scoring: Displays tracks with harmonic and tempo compatibility based on local scoring.
- Tag Health: Identifies missing metadata fields (ISRC, Genre, etc.) for the specific track.
- Provider Links: Generates buy-links for external stores like Beatport or Bandcamp.
Sources: apps/desktop/src/App.tsx:1020-1160, apps/desktop/src/lib/library.ts:250-264
Data Flow & IPC
The UI communicates with the Rust core using typed commands and listens for asynchronous events to update progress bars and library state.
IPC Command Table
| Command | Purpose | File Source |
|---|---|---|
scan_folder | Initiates recursive file system scanning for audio files. | App.tsx:645 |
list_tracks | Fetches filtered and sorted track summaries from SQLite. | App.tsx:437 |
analyze_library | Triggers the ONNX-based audio analysis pipeline. | App.tsx:661 |
enrichment_preview | Fetches metadata proposals from online providers. | App.tsx:516 |
get_artwork | Retrieves base64-encoded image data for a track. | App.tsx:90 |
Event Handling
The application uses Tauri's event system to handle long-running tasks without blocking the UI.
This sequence illustrates how the UI remains responsive during a folder scan by listening for progress events.
Sources: apps/desktop/src/App.tsx:556-578, apps/desktop/src/App.tsx:645-659
Library Logic Helpers
To ensure testability, the application separates pure logic from React components in library.ts. These helpers handle formatting, normalization, and client-side search filtering.
Key Helper Functions
| Function | Description |
|---|---|
normalizeFilters | Cleans filter drafts for the IPC boundary, ensuring non-finite numbers are removed and keys are uppercased. |
formatDuration | Converts milliseconds to a m:ss string format. |
formatKey | Determines the display string by prioritizing Camelot codes over Classical names. |
matchesQuery | Performs case-insensitive search across title, artist, album, and file path. |
scanPercent | Calculates progress percentage, defaulting to 25% if the total file count is unknown. |
Sources: apps/desktop/src/lib/library.ts:88-124, apps/desktop/src/lib/library.ts:168-174, apps/desktop/src/lib/library.ts:192-205, apps/desktop/src/lib/library.ts:280-283
Configuration & Environment
The desktop environment is configured via tauri.conf.json, defining window dimensions, security policies (CSP), and build commands.
- Content Security Policy (CSP):
default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; style-src 'self' 'unsafe-inline'; font-src 'self' data:; img-src 'self' data: asset: http://asset.localhost; - Window Defaults: 1280x800 resolution with a minimum size of 900x600.
- Build Integration: Uses
pnpm devfor development andpnpm build(which runstsc && vite build) for production assets.
Sources: apps/desktop/src-tauri/tauri.conf.json:11-38, apps/desktop/package.json:8
Conclusion
The Desktop App & React UI serves as a specialized interface for professional DJ preparation. By combining a modern React frontend with a robust Rust-based Tauri backend, the system provides a responsive experience for managing large music collections. Its architecture ensures that intensive tasks like folder scanning and audio analysis occur asynchronously, while specialized tools like the Track Inspector and Tag Health auditor provide high visibility into library data.