CrateMind Academy

Problem

DJs building a set from their own library have to manually track which tracks are harmonically compatible (matching musical keys via the Camelot wheel) and manage energy flow across a set by ear and memory, a process existing DJ software leaves largely manual. Separately, DJs who record their mixes have no structured, measurable feedback on the mix itself — no tool analyzes a finished recording and teaches against what actually happened, the way a coach would. Building both as separate products risked the two disagreeing about the same track's harmonic or energy score depending on which surface calculated it, which for a product whose core promise is defensible measurement would be the one bug that breaks trust entirely.

What was built

A native Mac app that reads a DJ's existing library (Serato, Rekordbox, Traktor, or Engine DJ, read-only, never modifying the source files) and generates a harmonically mixed, energy-arced set in one click, with tools to browse the library visually, build sets by natural-language intent, and practice against generated sets. A companion web service ("Mix MRI") takes a recorded mix a DJ has already played and analyzes it, scoring it against the same measurement engine the app uses and surfacing lessons the DJ can act on, functioning as a coaching layer rather than just a metrics dashboard. Both halves are built and functionally exercised end to end, including a proven chunked-import path capable of carrying a real library on the order of 100,000 tracks, but the product has not shipped publicly yet: it is not yet listed on the App Store (blocked on enrolling in the Apple Developer Program) and the academy web service has no live public domain attached yet.

Technical approach

The architecture's central discipline is a single canonical musicology engine (HarmonicEngine, a Swift package covering Camelot key math, sequencing, and energy scoring) exposed to the Python-based academy service through crate-engine, a JSON CLI/HTTP shim rather than a reimplementation — an earlier Python musicology module (api/harmonic.py) was deleted specifically to remove the risk of the two surfaces drifting apart, which the team states already happened once before the shim existed. The shared contract/ directory defines the wire format (Track schema) both the Swift app and Python service serialize against, with an explicit rule that a track that cannot be identified is refused rather than silently falling back to encoding its filesystem path — a stated privacy and correctness guard. The academy runs as a FastAPI service in Docker (port 8062) backed by Postgres and Redis containers shared with an unrelated project to keep memory pressure off a single Mac host, while the Mix MRI analysis worker itself runs natively via launchd rather than in Docker because a two-hour mix needs roughly 5GB of memory the Docker VM isn't provisioned for. Source audio is deleted immediately after analysis (in a finally block) with a daily reaper script and an R2 lifecycle rule as backstops, and the team enforces a rule that every number shown to a user must trace to an actually measured quantity — unscored dimensions render as null rather than a defaulted or averaged value, specifically to avoid a chart that looks complete but isn't. Both test harnesses enforce a minimum assertion-count floor and fail the build if fewer assertions run than expected, added after a review found 17 assertions that could silently disappear while the suite still reported zero failures. A network flag (Feature.librarySync) currently keeps the macOS app making zero network calls at all, which is what lets the pending App Store privacy label claim "Data Not Collected" — sync and account features are deliberately gated off rather than shipped half-wired.

Creative approach

Craft

The product deliberately narrowed its 1.0 surface area via an explicit scope cut: Library Map, Crate Builder, Set Architect, and Practice ship; Events and Playlist Import are deferred; a Clients/CRM module and an Equipment manager were fully built and then cut from the shipping product rather than deleted from the codebase, kept only so they continue compiling and can't silently rot. The landing page pitches a dark, HUD-styled visual identity (near-black background, cyan/violet/magenta gradient accents, a glassy panel system) matching the product's positioning as a precision instrument for a technical hobbyist audience rather than a consumer lifestyle app. Copy leans on specificity over hype — the pitch names the exact library formats it reads (Serato, Rekordbox via XML export, Traktor, Engine DJ) and states plainly that it never modifies the DJ's own files, which functions as both a trust signal and a scope boundary for what the product will and won't touch.

Reframe

The defining product decision is refusing to let the app and the coaching service be two different products that happen to share a name. Because both surfaces score the same track, a version skew between them would produce visibly contradictory numbers for the same input, undermining the entire pitch that the product's numbers are trustworthy measurement rather than vibes. That constraint (one engine, two consumers, no silent fallback) shaped the repo structure, the deploy discipline, and a dedicated health check that alerts specifically on engine-version drift between the installed service binary and the source tree — a real failure mode, not a hypothetical one: the launchd-run service loads a compiled binary rather than the source tree directly, so a change to the engine or its contract that isn't followed by a reinstall step leaves the running service silently scoring against stale logic while the app scores against current logic, which is exactly the disagreement the shared-engine design exists to prevent. The team states plainly that this exact drift already happened once, before the crate-engine shim existed, which is the failure the whole shared-engine architecture was built to close off rather than a risk reasoned about in the abstract.

Process and what failed

A formal internal assessment (dated 2026-07-25) found and closed 17 "must fix before submit" defects, including one where every build before that date used an unsigned/unsandboxed configuration flag, which meant two Pro features that later broke under real App Store sandboxing had never actually been tested under sandbox enforcement — the bug was invisible until the build was finally signed correctly. About 1,700 lines of engine code (transition composition, performance-capture/analytics/learning modules, a Serato history reader, batch/packing-list features) are fully built and unit-tested but have zero production callers in the actual app — explicitly logged as "built" but "not in the product," a candid distinction the team draws rather than counting dead code as shipped functionality. The energy-scoring algorithm was also found to have a calibration bug where it computes relative to the DJ's whole library rather than an absolute scale, so a 126 BPM house track on a wide-BPM library could compute as "mid" energy and be invisible to a "Peak Hour" query that demands "high" and a narrow BPM band — logged as an open calibration decision rather than patched blind.

Outcome

Both halves of the product are built and pass their respective test suites, with a proven live run syncing 5,250 real tracks end-to-end through the shared engine with zero identifying paths leaking across the wire. The product has not launched publicly: it is not yet on the App Store, pending Apple Developer Program enrollment and code-signing setup, and the academy web service has no live domain attached yet (no cratemind-branded zone existed in the account as of the last handoff, with the .com already registered by an unrelated party). Calibration data (rated real mixes) needed to make the Mix MRI scoring authoritative is also still pending.