Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
DJ Assistant is a local-first desktop application designed to accelerate DJ set preparation. It uses a non-destructive pipeline to analyze audio, clean metadata, and generate performance cues without modifying the original source files.
The system follows a split architecture where a high-performance Rust core handles audio processing and data management, while a React-based frontend provides the user interface. Communications between these layers occur via a typed Inter-Process Communication (IPC) bridge provided by Tauri v2.
Sources: README.md:148-161, CHANGELOG.md:113-120
System Components
The project is organized as a monorepo containing several distinct packages and crates that separate concerns between the desktop client, shared logic, and optional cloud services.
Core Architecture Layers
| Component | Responsibility | Technology |
|---|---|---|
| Frontend | User Interface, Library View, Set Builder | React 18, TypeScript, Tailwind CSS |
| Desktop Shell | IPC Bridge, Window Management, OS Integration | Tauri v2 |
| Core Logic | Scanning, Fingerprinting, SQLite Management | Rust (dj-assistant-core) |
| Analysis Engine | Audio Decoding, ONNX Inference, DSP | Rust (dj-assistant-analysis), ONNX Runtime |
| Cloud API | Optional B2B Collaboration, Metadata Enrichment | Fastify (Node.js), PostgreSQL |
Sources: README.md:214-235, apps/desktop/src-tauri/Cargo.toml:23-31
High-Level Component Flow
The following diagram illustrates how the desktop application components interact with local resources and optional external services.
The desktop application remains fully functional offline, as the core analysis path and data storage reside entirely on the user's machine.
Sources: README.md:237-270, apps/desktop/src-tauri/Cargo.toml:34-40
Data Management
DJ Assistant uses SQLite as its primary local data store, utilizing Write-Ahead Logging (WAL) mode for performance. The database stores track metadata, analysis results, and skill execution history.
Database Schema
The initial schema focuses on tracks, workspaces, and performance markers (cues).
The system uses BLAKE3 fingerprinting to identify files, ensuring that duplicate files within a workspace are detected and handled through a unique_hash_per_workspace constraint.
Sources: apps/desktop/src-tauri/migrations/001_initial_schema.sql:4-67, CHANGELOG.md:144-150
Preparation Pipeline
The application processes music through a series of "Skills"—scoped, reversible processing units. Each stage provides a preview and allows for undo actions through snapshots stored in the skill_runs table.
Processing Stages
- Analyze: Detects BPM, Key, Beat Grid, and Phrasing using ONNX models and the
Symphoniadecoding library. - Clean: Normalizes metadata using fuzzy clustering and persistent aliases.
- Cue: Places hot cues and memory cues based on detected phrase boundaries.
- Sequence: Uses a deterministic Beam Search to order tracks based on harmonic and energy compatibility.
- Export: Generates standard formats like rekordbox XML or Serato crates.
Sources: README.md:104-142, CHANGELOG.md:46-95
Analysis Sequence
The analysis engine executes multiple DSP tasks in a specific order to derive track structure.
Analysis Engine Foundation
The analysis engine (dj-assistant-analysis) is a standalone Rust crate that operates independently of the Tauri runtime. It manages several deterministic analyzers:
- BPM + Beat Grid: Uses spectral-flux onset envelopes and autocorrelation.
- Key Detection: Employs Krumhansl-Kessler key-finding via 12-bin pitch-class profiles.
- Loudness: Measures EBU R128 integrated LUFS and true peak.
- Vocal Presence: Heuristic detection using mid/side STFT energy ratios.
Sources: CHANGELOG.md:52-85, apps/desktop/src-tauri/Cargo.toml:29-31
Summary
The architecture of DJ Assistant prioritizes local privacy and non-destructive automation. By decoupling the performance-heavy Rust analysis engine from the React UI via Tauri's IPC, the system maintains high responsiveness even during intensive audio processing. All automation is anchored by a persistent SQLite database that tracks every modification as a reversible "Skill," ensuring the DJ remains in full control of the final output.
Sources: README.md:148-161, CHANGELOG.md:104-125