// AUDIO_HAXOR — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

AUDIO_HAXOR is a Tauri v2 desktop application for cataloging, analyzing, and arranging music-production assets. The Rust backend (src-tauri/) walks the filesystem to index VST2/VST3/AU/CLAP/AAX plugins, audio samples, DAW projects across 13 formats, MIDI files, presets, PDFs, and video reference material into a SQLite catalog. A separate JUCE 8 sidecar process (audio-engine) handles device I/O, plugin hosting, sample-accurate playback, and waveform / spectrogram rendering over a stdin/stdout JSON protocol. The frontend is a WebKit-rendered cyberpunk HUD with 51 JS modules driving the grid views, command palette, tray popover, and ALS Ableton-project generator.

#SUBSYSTEM BREAKDOWN

The Rust backend (75,711 LOC across 47 files) is partitioned below by role. db.rs dominates — the entire SQLite schema (46 tables, 93 indices), all CRUD helpers, plus filter / facet / stats queries live in a single file. lib.rs is the Tauri-command surface (291 registered IPC handlers) plus app setup. ALS / MIDI / track generators are the largest concentration of domain logic, including the trance-arrangement state machine and Ableton-project XML emitter.

* Test / bench percentages are relative to production LOC (75,711), not part of the 100% above.

$TOP 15 FILES BY SIZE

The 15 largest files in src-tauri/src/ account for 80.8% of the Rust production slice. db.rs is by far the heaviest — SQLite is the catalog spine, every query routes through it, and inlined SQL templates plus filter-stat aggregations push the file past 16k lines.

$TOP 10 FRONTEND MODULES

The 10 largest JS modules under frontend/js/ account for 59.2% of the 58,324-line frontend slice. audio.js at 8,759 lines is the playback / waveform / spectrogram / drag-source / player-history controller — the longest single JS file in the app.

@PROCESS ARCHITECTURE

Three processes per running instance: the Tauri shell (main), the WebKit frontend, and the JUCE audio-engine sidecar. The shell owns the SQLite catalog and filesystem walkers; the WebView drives the UI; the sidecar holds juce::AudioDeviceManager, hosts plugin instances, and renders waveforms. The shell talks to the frontend over Tauri's IPC bus (291 commands), and to the sidecar over a stdin/stdout JSON line protocol.

  ┌──────────────────────────────────────────────────────────────────┐
  │                  AUDIO_HAXOR DESKTOP (Tauri v2)                  │
  ├──────────────────────────────────────────────────────────────────┤
  │                                                                  │
  │   ┌────────────────────┐         ┌────────────────────────────┐  │
  │   │  WebView frontend  │ ◀─────▶ │   Rust shell (src-tauri)   │  │
  │   │  (frontend/)       │   IPC   │   ────────────────────     │  │
  │   │   51 JS modules    │   291   │   • 291 #[tauri::command]  │  │
  │   │   58,324 LOC       │   cmds  │   • SQLite catalog (db.rs) │  │
  │   │   WebKit (release) │  events │     46 tables / 93 indices │  │
  │   │   http (dev)       │ ──────▶ │   • Rayon-parallel walkers │  │
  │   │                    │         │   • Symphonia metadata     │  │
  │   │   • Grid views     │         │   • SHA-256 fingerprinter  │  │
  │   │   • Cmd palette    │         │   • ALS generator (XML+gz) │  │
  │   │   • Tray popover   │         │   • i18n catalog loader    │  │
  │   │   • Visualizer     │         │     27 locales / 3,279 keys│  │
  │   │   • Settings       │         │   • objc2 macOS bindings   │  │
  │   └────────────────────┘         └─────────────┬──────────────┘  │
  │                                                │                 │
  │                                  stdin/stdout JSON line protocol │
  │                                                ▼                 │
  │                                  ┌─────────────────────────────┐ │
  │                                  │  audio-engine sidecar       │ │
  │                                  │  ─────────────────────────  │ │
  │                                  │  • C++20 / JUCE 8.0.4       │ │
  │                                  │  • 5,802 LOC (7 files)      │ │
  │                                  │  • juce::AudioDeviceManager │ │
  │                                  │  • Plugin hosts:            │ │
  │                                  │    VST3 / AU / CLAP*        │ │
  │                                  │  • Sample-accurate playback │ │
  │                                  │  • Waveform render          │ │
  │                                  │  • Spectrogram (FFT)        │ │
  │                                  │  • AU CocoaUI patch (JUCE 8)│ │
  │                                  │  • Crash handler / watchdog │ │
  │                                  └─────────────────────────────┘ │
  │                                                                  │
  └──────────────────────────────────────────────────────────────────┘
                          │
                          │ persistent state
                          ▼
  ┌──────────────────────────────────────────────────────────────────┐
  │  ~/Library/Application Support/com.menketechnologies.audio-haxor │
  │  ───────────────────────────────────────────────────────────     │
  │   • catalog.sqlite     (46 tables, FTS-eligible search)          │
  │   • prefs.json         (window state, scan dirs, theme)          │
  │   • cache/             (waveform PNGs, spectrogram PNGs)         │
  │   • history/           (per-domain snapshot JSONs)               │
  └──────────────────────────────────────────────────────────────────┘
      

&SCANNERS & WALKERS

Seven independent scanners plus a unified walker that classifies and emits inventory rows for all domains in one filesystem traversal. Every scanner is Rayon-parallel; cancellation is via AtomicBool stop-flags checked per file. The unified_walker at 1,433 lines collapses 7 individual walkdir passes into one, which is the path used by the "Scan All" button.

!ALS PROJECT GENERATOR

16,773 lines across six files compose the Ableton Live Set generator — the largest single feature in the app by code mass (22.2% of the Rust slice). Output is gzip'd XML that opens natively in Ableton Live; the generator selects samples from the catalog by genre / BPM / key constraints, lays out scenes, routes groups, attaches sidechain compressors, and emits the complete project file with no post-processing required.

// EMBEDDED XML TEMPLATES (raw inline assets in src-tauri/src/)

• empty_project_template.als.gz — gzip'd minimal Ableton 11+ project, deserialized then mutated
• audio_track_template.xml — <AudioTrack> fragment with default routing
• midi_track_template.xml — <MidiTrack> fragment with default channel
• group_track_template.xml — <GroupTrack> fragment with default color
• group_sidechain_compressor_template.xml — <DeviceChain> with sidechain wiring
• master_eq8_hpf_template.xml — <Eq8> with high-pass enabled
• master_limiter_template.xml — <Limiter> with ceiling 0.0 dB

~AUDIO ENGINE SIDECAR

A separate process built with JUCE 8.0.4 (pulled via CMake FetchContent) handles all device I/O, plugin hosting, sample-accurate playback, and offscreen rendering. The Rust shell spawns it as a child process; communication is line-delimited JSON over stdin/stdout. Crash isolation: a sidecar segfault never takes the main app down — the shell restarts it with state reload.

The CMake build patches juce::AudioUnitPluginWindowCocoa::createView at configure-time: stock JUCE 8 prefers the async RequestViewController path over the legacy CocoaUI path, but the XPC delivery never arrives in a spawned sidecar process, so AUv2 plugins (UAD, Sonimus, etc.) would render permanently blank. The patch gates the async branch on pluginView == nil, restoring the legacy attach path. Idempotent — re-running CMake is a no-op.

%SQLITE CATALOG

46 tables and 93 indices, all bundled in src-tauri/src/db.rs (16,310 LOC). The catalog covers every inventory domain plus history snapshots, KVR plugin metadata, waveform / spectrogram caches, and per-row notes / tags / favorites. rusqlite with the bundled feature so the binary ships its own SQLite — no system dependency.

// SCHEMA DOMAINS

^IPC COMMAND SURFACE

291 IPC commands defined in lib.rs and registered via tauri::generate_handler!. The frontend invokes them through window.__TAURI__.core.invoke(name, args); frontend/js/ipc.js (2,291 LOC) wraps each one with a typed helper. Domains below break down what the frontend can ask the shell to do.

*INTERNATIONALIZATION

3,279 English keys mirrored across 27 locales. Catalogs ship as JSON under i18n/; app_i18n.rs (2,044 LOC) handles runtime resolution with English fallback. The frontend pulls catalogs once on startup and substitutes keys at render time. 43 Python scripts under scripts/ (6,226 LOC) handle catalog generation, gap-fill, audit, and locale-key sync.

Locales: cs, da, de, el, en, es, fi, fr, he, hi, hu, id, it, ja, ko, nl, no, pl, pt, pt-BR, ro, ru, sv, tr, uk, vi, zh-Hans. Audit tooling: i18n_catalog_audit.py diffs each non-EN catalog against EN for missing keys, placeholder drift, and empty values.

.TESTS

9,481 #[test] functions across 116 Rust integration modules in src-tauri/tests/, totaling 64,507 LOC. The largest single test file (handcrafted_tables_massive.rs at 22,878 LOC) is a table-driven regression catcher pinning behaviors that earlier bugs broke. Rule: never delete a test file; never write generic boilerplate tests; every test catches a real bug or pins a real behavior.

// TOP TEST MODULES

+DEPENDENCIES

51 direct dependency entries in src-tauri/Cargo.toml across [dependencies], target-specific macOS, [build-dependencies], and [dev-dependencies]. Strict preference for foundational crates over fashionable ones; every dep is audited against the build-clean-in-5-years bar.

;PUBLIC API SURFACE

The Rust shell is built as a single rlib (app_lib) consumed by src-tauri/src/main.rs. The public surface is the 291 Tauri-IPC commands registered from lib.rs; internally the crate spans 47 modules.

?KEY DESIGN DECISIONS

Where the implementation could have gone either way, and why this path was taken.