docs: architecture map (initial 5-slice generation, 105 pages)

Five-slice navigable map of the entire codebase under docs/architecture-map/. Each slice is a self-contained breadcrumbed sub-tree: 01-frontend (16) Svelte/SvelteKit UI 02-tauri-runtime (26) src-tauri commands + lifecycle 03-audio-transcription (16) audio + transcription crates 04-llm-formatting-mcp (19) llm, ai-formatting, mcp, cloud 05-core-storage-hotkey-build core, storage, hotkey, workspace, (26) CI, dev glue Plus master README.md and data-flow-end-to-end.md tracing audio bytes from microphone to FTS5 search to MCP read. Generated by 5 parallel subagents on 2026/05/09 against HEAD 3c47000. Each page has YAML frontmatter, file:line code refs, sibling cross-links, plain-English summaries. Aggregated debt surfaced (full lists in master README): RB-08 macOS power assertion, schema head drift v14 vs v15, VAD blocked on ort version conflict, streaming primitives not wired into live.rs, no prompt versioning, MCP has no auth, cloud-providers in-memory keystore, SettingsPage 2 484 LOC, commands/live.rs 1 737 LOC, dual theme system, brand rename to Lumenote pending across the codebase. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-09 14:04:13 +01:00
parent 3c47000ea9
commit a1f3f3f134
105 changed files with 11266 additions and 0 deletions
--- a/docs/architecture-map/03-audio-transcription/build-tokenizers-guard.md
+++ b/docs/architecture-map/03-audio-transcription/build-tokenizers-guard.md
@@ -0,0 +1,94 @@
+---
+name: Build script (Windows tokenizers guard)
+type: architecture-map-page
+slice: 03-audio-transcription
+last_verified: 2026/05/09
+---
+
+# Build script (Windows tokenizers guard)
+
+> **Where you are:** [Architecture map](../README.md) → [Audio + Transcription](README.md) → Build script
+
+**Plain English summary.** `magnotia-transcription/build.rs` reads `Cargo.lock` and refuses to compile on Windows if the `tokenizers` crate ever lands in the workspace dependency graph. Linking `whisper-rs-sys` and `tokenizers` together has been a repeated MSVC C-runtime conflict (Whispering v7.11.0 shipped a broken Windows build over exactly this). On non-Windows the check is a `cargo:warning`, not a fatal error, so the failure surfaces at CI build time rather than waiting for a Windows ship.
+
+## At a glance
+
+- Crate: `magnotia-transcription`
+- Path: `crates/transcription/build.rs`
+- LOC: 73
+- External deps: stdlib only (`std::env`, `std::fs`).
+- Internal callers: cargo invokes this automatically because `Cargo.toml` declares `build = "build.rs"`.
+
+Public surface: none (build scripts have no callable surface).
+
+## What's in here
+
+```rust
+fn main() {
+    println!("cargo:rerun-if-changed=build.rs");
+    let target_os = env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
+    let manifest_dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap_or_else(|_| ".".into()));
+
+    // Walk up to workspace root: crates/transcription/ -> crates/ -> root
+    let workspace_root = manifest_dir
+        .ancestors()
+        .find(|p| p.join("Cargo.lock").exists())
+        .map(PathBuf::from);
+
+    let Some(root) = workspace_root else { return; };
+    let lock_path = root.join("Cargo.lock");
+    println!("cargo:rerun-if-changed={}", lock_path.display());
+
+    let lock = match fs::read_to_string(&lock_path) {
+        Ok(s) => s,
+        Err(_) => return,
+    };
+
+    let has_tokenizers = lock
+        .lines()
+        .any(|line| matches!(line.trim(), "name = \"tokenizers\""));
+
+    if !has_tokenizers { return; }
+
+    if target_os == "windows" {
+        panic!(
+            "magnotia-transcription: the `tokenizers` crate appears in Cargo.lock and this is a \
+             Windows build. ..."
+        );
+    }
+
+    println!(
+        "cargo:warning=magnotia-transcription: `tokenizers` crate is in the dependency graph. \
+         This build is non-Windows so the link will succeed, but Windows builds will panic ..."
+    );
+}
+```
+
+## Data flow
+
+```
+cargo invoke
+  └─ build.rs
+      ├─ rerun-if-changed=build.rs
+      ├─ ancestors().find(Cargo.lock) → workspace root
+      ├─ rerun-if-changed=Cargo.lock
+      ├─ scan for `name = "tokenizers"`
+      └─ if found:
+            target_os == windows? → panic!("brief item #6")
+            else → cargo:warning
+```
+
+## Watch-outs
+
+- **`rerun-if-changed=Cargo.lock` is the trigger.** Adding tokenizers without changing this crate's source still re-runs the script the next build because the lockfile changed.
+- **The string match is brittle on purpose.** Looking for the literal `name = "tokenizers"` line in `Cargo.lock` is what TOML pretty-prints. A future cargo version that emits the lockfile differently could miss this. Mitigation: keep the test simple and review on cargo upgrade.
+- **The non-Windows path is a warning, not an error.** A CI matrix job on Linux will pass with a yellow message; Windows will fail at build. Fine for a desktop project that ships from Linux first; surprising if anyone ever assumes "Linux green = ready to ship".
+- **Brief item #6 reference.** The panic message points at `docs/whisper-ecosystem/brief.md` item #6. Do not lose that pointer in any rewrite — the failure mode is non-obvious without the historical context.
+- **`workspace_root` walk falls back gracefully.** If no `Cargo.lock` is found in any ancestor (first-ever cargo run), the script returns early. Subsequent builds will pick up the lock.
+- **No way to override.** A maintainer who *wants* to ship `tokenizers` on Windows must delete this `build.rs`, or carry a sidecar process that links tokenizers in its own binary. There is no escape hatch env var.
+
+## See also
+
+- [Transcription whisper](transcription-whisper.md) — `whisper-rs-sys` is the link target this guard protects.
+- [Cargo features](cargo-features.md) — same brief-item #6 family of decisions.
+- `docs/whisper-ecosystem/brief.md` — the full incident background.