This directory holds Architecture Decision Records (ADRs) - short documents that capture a significant decision, the context that forced it, and the consequences we accepted.
Record a decision here when it is hard to reverse, affects more than one team or component, or a future reader would reasonably ask "why was it done this way?". Routine, easily-reversible choices do not need an ADR.
- One file per decision, named
NNNN-short-title.md(zero-padded, sequential). 0001onward; never renumber or delete an ADR.- An ADR is immutable once Accepted. To change a decision, write a new ADR
and set the old one's status to
Superseded by ADR-NNNN. - Use
template.mdas the starting point.
Use the write-adr skill - it picks the next number, fills in the date, and
scaffolds the file from the template.
| ADR | Title | Status |
|---|---|---|
| 0001 | Record architecture decisions | Accepted |
| 0002 | Browser app with Python model workers, deferring Tauri | Superseded by 0018, 0019 |
| 0003 | Frontend audio mixing via Web Audio | Superseded by 0017 |
| 0004 | Style is a weighted prompt blend; tempo is not a parameter | Accepted |
| 0005 | Hardware control via Web MIDI in the frontend | Accepted |
| 0006 | Cue output via a second audio sink | Superseded by 0017 |
| 0007 | FLX4 phones jack via a backend cue sink | Superseded by 0017 |
| 0008 | Color FX as one-knob curves at a pre-fader insert | Accepted |
| 0009 | Freeze pads loop played audio at the channel head | Accepted |
| 0010 | Beat detection on the output, behind an honesty gate | Superseded by 0025 |
| 0011 | Deck-to-deck style sampling via audio embeddings | Accepted |
| 0012 | Generated pads via a spawned sa3_mlx subprocess | Accepted |
| 0013 | Playback decks play decoded tracks; loading decides the mode | Accepted |
| 0014 | Beat-matching via varispeed tracks against the measured stream | Accepted |
| 0015 | Hot cues in deck state, loops on the buffer source | Proposed |
| 0016 | Beat loops: length-scaling over the M21 loop region | Proposed |
| 0017 | Native Rust audio engine, superseding frontend Web Audio mixing | Accepted |
| 0018 | Native macOS shell: Tauri with Python sidecars | Accepted |
| 0019 | PCM transport from the Python sidecars to the Rust audio engine | Accepted |
| 0020 | Rust as the single interface-state store, exposed via a native MCP server | Proposed |
| 0021 | Split master and cue to independent output devices (dual-mode) | Accepted |
| 0022 | Persist generated samples and loops in a samples library | Accepted |
| 0023 | MIDI note and drum conditioning over the deck control channel | Accepted |
| 0024 | Key detection in the Rust audio engine, behind an honesty gate | Accepted |
| 0025 | Beat detection in the Rust audio engine | Accepted |
| 0026 | Lane-driven variable chunk segmentation for the modulation timeline | Accepted |
| 0027 | Headphone preview ("audition") for library items | Accepted |
| 0028 | Stable Audio 3 LoRA finetunes via the MLX path | Accepted |
| 0029 | Output resampling for devices with no 48000/f32 config | Accepted |
| 0030 | Track decode and offline track analysis in the Rust shell | Accepted |
| 0031 | Native MIDI in the Rust core, superseding Web MIDI | Accepted |
| 0032 | Standalone MIDI keyboard window, routing decoupled from steering | Accepted |
| 0035 | Dual-envelope beat detection with fast change invalidation | Accepted |
| 0036 | Curation metadata in the library registry; playlists as m3u8 files | Proposed |
| 0037 | Audio-to-audio from library songs: the shell cuts the window | Proposed |