Developer Quick Start
Relevant source files
The following files were used as context for generating this wiki page:
DJ Assistant provides a local-first environment for DJ set preparation, automating metadata cleanup, audio analysis, and track sequencing. This guide assists developers in setting up the monorepo environment, understanding the multi-language architecture, and running local validation pipelines.
Sources: README.md:1-24, README.md:126-130
Environment Setup
The project uses a monorepo structure managed by pnpm for the frontend and API, alongside a Cargo workspace for Rust-based core logic.
Prerequisites
You must install the following toolchain versions:
- Node.js: ≥ 20
- pnpm: 10.14+
- Rust: 1.82+
Sources: README.md:310-312, package.json:5
Installation Steps
- Clone the repository and enter the directory.
- Install Node.js dependencies using
pnpm install. - Launch the desktop development environment with
pnpm dev:desktop. - (Optional) Launch the cloud API using
pnpm dev:api.
Sources: README.md:314-320
Workspace Structure
The monorepo contains three Node.js packages and two primary Rust crates. The desktop application utilizes Tauri v2 to bridge the React frontend with the Rust audio engine.
| Package / Crate | Technology | Description |
|---|---|---|
@dj-assistant/desktop | React 19, Vite 8, Tauri v2 | Main desktop GUI and IPC bridge. |
@dj-assistant/api | Fastify 5, TypeScript | Optional cloud API for collaboration. |
@dj-assistant/shared | TypeScript | Shared types and utility contracts. |
dj-assistant-core | Rust | Handles file scanning, BLAKE3 fingerprinting, and SQLite logic. |
dj-assistant-analysis | Rust, ONNX Runtime | Audio engine for BPM, key, and phrase detection. |
Sources: README.md:327-340, apps/desktop/package.json:18-28, apps/api/package.json:15-18
Architectural Data Flow
The following diagram illustrates how the desktop application communicates between the frontend UI and the performance-critical Rust core.
The desktop shell uses Tauri v2 to execute performance-heavy tasks like audio decoding and SQLite operations in Rust while maintaining a responsive React frontend.
Sources: README.md:213-234, apps/desktop/src-tauri/Cargo.toml:17-25
Development Commands
The root package.json provides scripts to manage the entire workspace, including linting, testing, and building.
General Workspace Scripts
pnpm lint: Runs Prettier and ESLint across all packages.pnpm typecheck: Validates TypeScript types across the monorepo.pnpm test: Executes Node.js test suites in all packages.pnpm format: Applies Prettier formatting to all supported files.
Sources: package.json:8-16
Rust-Specific Scripts
pnpm rust:fmt: Checks Rust code formatting viacargo fmt.pnpm rust:clippy: Runs the Clippy linter with warnings treated as errors.pnpm rust:test: Runs the complete Rust test suite.pnpm rust:test:portable: Runs tests that do not require specific OS hardware (core, analysis, and schema tests).
Sources: package.json:17-21
CI and Local Validation
Before submitting a Pull Request, you must ensure all local checks pass. The project employs a "Local CI" script that mirrors the GitHub Actions pipeline.
Local CI Options
| Command | Action |
|---|---|
pnpm ci:local | Runs lint, typecheck, JS tests, and all Rust tests. |
pnpm ci:local:portable | Skips Rust tests requiring MSVC or specific audio hardware. |
Sources: package.json:22-23, README.md:322-325
Contributing Guidelines
All contributions must follow the Coding Standards and use Conventional Commits.
- Read the Canonical Documentation for product vision.
- Branch from the current development branch.
- Write or update tests for any changes.
- Ensure
pnpm ci:localpasses before requesting a review.
Sources: CONTRIBUTING.md:12-36