slopsmith-desktop had no CLAUDE.md, so an AI agent landing in this
repo had no obvious starting point — README.md is install-focused
(Windows/macOS/Linux download instructions) and wouldn't lead an
agent to docs/. Adding a brief root-level guide that:
- Orients the agent on what this repo is vs the sister
byrongamatos/slopsmith repo (audio engine + Electron shell here;
library + chart parsing + visualization there)
- Indexes docs/ contents
- Cross-links the slopsmith-side docs that describe what consumes
the IPC surface this engine exposes
- Captures the threading invariants, build-flag list, common
gotchas (audio rebuild lock, ELECTRON_RUN_AS_NODE, port 18000)
in one place rather than scattered across CLAUDE.md fragments
in the dev workspace
Modelled on slopsmith/CLAUDE.md's style — technical-but-
conversational, ATX headings, file paths in backticks, link-heavy.
Keeps the new audio-engine-architecture.md as the canonical deep-
dive; this file is a navigation hub.
Signed-off-by: Kris Anderson <topkoa@gmail.com>
(cherry picked from commit caac6aa9ea8354a489ee557a54193415fe416c9a)
New docs/audio-engine-architecture.md describes the native audio + ML
detection internals: the audio device callback, the lock-free input
ring buffer, two-tier pitch detection (YIN + Basic Pitch via ONNX),
the ChordScorer constraint path, the NoteVerifier background thread,
the N-API surface, and the threading invariants every contributor
needs to keep in mind.
The detection pipeline now has substantial moving parts (input ring,
two detectors, one verifier thread, sandboxed plugin hosting,
split-mode duplex) and the only documentation lived in opening
comments at the top of each source file. This doc is the picture,
with a component map up top and cross-references to the actual code.
Renderer-side companion documented in a sibling PR against
byrongamatos/slopsmith.
Signed-off-by: Kris Anderson <topkoa@gmail.com>
(cherry picked from commit 5a96b33eef90f28e9e7f1091c85e0606ddc260fe)
