Add all scaffolding, design, and decision documentation AKA first commit

2026-06-30 16:12:55 -05:00
parent b19e01c171
commit aae22a0e23
63 changed files with 4690 additions and 0 deletions
@@ -0,0 +1,49 @@
+# ADR-0001 — Application shell: Tauri 2
+
+- **Status:** Accepted
+- **Date:** 2026-06-30
+- **Deciders:** WA core team
+- **Context source:** Design doc §"Desktop UI Layer", NFR resource-usage requirements
+
+## Context
+
+The design doc leaves the UI framework open (WPF/.NET, WinUI 3, Electron, or native) and the
+user's only hard constraint is: **fast and low memory footprint**. WA is Windows-first but the
+doc mentions possible future Windows-on-ARM and (implicitly) cross-platform support. The app
+must idle like a lightweight background process (NFR-RES-1) yet present a modern, themeable UI
+with waveforms, live transcript streaming, and rich note editing.
+
+## Options considered
+
+1. **Electron + native modules** — fastest UI development, largest ecosystem, but bundles
+   Chromium → high baseline memory and large binaries. Conflicts with the low-overhead NFRs.
+2. **.NET + WinUI 3** — excellent native Windows + hardware story (Windows ML, DirectML,
+   WASAPI), good performance. But heavier runtime than Rust/native, Windows-locked, and a
+   larger install. Strong second choice.
+3. **C++ / Qt or fully native Win32** — lowest overhead, maximal control. Slowest UI iteration,
+   most code, hardest to staff for an open-source project.
+4. **Tauri 2 (Rust core + WebView2 + web UI)** — uses the OS WebView2 instead of bundling a
+   browser → small binaries, low idle memory; Rust core gives native-class performance for
+   audio/ML; web frontend keeps modern UX fast to build; cross-platform for the future.
+
+## Decision
+
+**Use Tauri 2.** It is the best fit for "fast + low memory + modern UI + open source":
+WebView2 keeps the footprint near-native while the Rust core handles WASAPI capture, whisper.cpp
+inference, ONNX Runtime, SQLite, and HTTP to Ollama with no GC pauses and direct access to the
+exact crates validated in `07-research-findings.md`.
+
+## Consequences
+
+- **Positive:** small footprint; one language (Rust) for all system-level services; mature
+  access to `wasapi`, `whisper-rs`, `ort`, `sherpa-onnx`, `outlook-pst`; future macOS/Linux/ARM
+  reachable without a rewrite.
+- **Negative / risks:** depends on WebView2 runtime (preinstalled on Win11, bootstrappable on
+  Win10); WASAPI loopback must poll (no event callback) — handled in the audio thread design;
+  web↔Rust boundary requires disciplined command/event contracts (`docs/04-api-contracts.md`).
+- **Rejected because:** Electron's memory cost contradicts the primary constraint; WinUI 3 and
+  native were viable but more Windows-locked / slower to iterate for an OSS project.
+
+## Revisit if
+WebView2 proves unreliable for real-time waveform/transcript rendering, or NPU tooling becomes
+materially better from .NET than from Rust.