// 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 57 JS modules driving the grid views, command palette, tray popover, lifecycle scripting hooks (stryke), and ALS Ableton-project generator.

#SUBSYSTEM BREAKDOWN

The Rust backend (66,416 LOC across 52 files) is partitioned below by role. db.rs dominates — the entire SQLite schema (36 tables, 76 indices), all CRUD helpers, plus filter / facet / stats queries live in a single file. lib.rs is the Tauri-command surface (320 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. Lifecycle scripting hooks (hooks.rs) and the stryke language-server bridge (stryke_lsp.rs / stryke_runner.rs) are the newest modules.

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

$TOP 15 FILES BY SIZE

The largest files in src-tauri/src/ by role weight. 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 keep the file past 13k lines even after the schema partition. Three former scanner heavyweights (unified_walker, audio_scanner, daw_scanner) are now 3-line re-export stubs — their implementations were extracted into the zpwr-crate workspace crate.

$TOP 10 FRONTEND MODULES

The largest frontend JS modules. The frontend/js/ slice is now 51,706 LOC across 57 modules; audio.js at 8,797 lines is the playback / waveform / spectrogram / drag-source / player-history controller — the longest single JS file in the app. file-browser.js (shown below) was extracted into the crates/zpwr-file-browser/webui bundle and is no longer part of the frontend/js/ count.

@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 (320 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   │   ────────────────────     │  │
  │   │   57 JS modules    │   320   │   • 320 IPC handlers       │  │
  │   │   51,706 LOC       │   cmds  │   • SQLite catalog (db.rs) │  │
  │   │   WebKit (release) │  events │     36 tables / 76 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,506 keys│  │
  │   │   • Settings       │         │   • objc2 macOS bindings   │  │
  │   └────────────────────┘         └─────────────┬──────────────┘  │
  │                                                │                 │
  │                                  stdin/stdout JSON line protocol │
  │                                                ▼                 │
  │                                  ┌─────────────────────────────┐ │
  │                                  │  audio-engine sidecar       │ │
  │                                  │  ─────────────────────────  │ │
  │                                  │  • C++20 / JUCE 8.0.4       │ │
  │                                  │  • 4,659 LOC (14 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     (36 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. These scanner / walker implementations were extracted into the shared crates/zpwr-crate workspace crate; src-tauri/src/ now keeps thin 3-line re-export stubs and the LOC figures below are for the implementations in zpwr-crate.

!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 (21.7% 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.3 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. Shared DSP primitives (channel strip, OLA time-stretch, stereo file source, lock-free streaming, spectrogram analysis) were extracted into the header-only crates/zdsp-core library consumed by the sidecar, which is why the in-tree C++ count is smaller than earlier reports.

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

36 source-declared tables (6 of them FTS5 virtual tables, which spawn additional shadow tables at runtime) and 76 indices, all bundled in src-tauri/src/db.rs (13,331 LOC; row/table type definitions shared from crates/zpwr-crate). 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

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

*INTERNATIONALIZATION

3,506 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. 45 Python scripts under scripts/ (6,443 LOC) handle catalog generation, gap-fill, audit, and locale-key sync.

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

.TESTS

9,503 #[test] functions across 118 Rust integration modules in src-tauri/tests/, totaling 64,892 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

50 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 320 Tauri-IPC commands registered from lib.rs; internally the crate spans 52 source files.

?KEY DESIGN DECISIONS

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