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>
This commit is contained in:
jars
@@ -0,0 +1,113 @@
|
||||
---
|
||||
name: Core constants
|
||||
type: architecture-map-page
|
||||
slice: 05-core-storage-hotkey-build
|
||||
last_verified: 2026/05/09
|
||||
---
|
||||
|
||||
# Core constants
|
||||
|
||||
> **Where you are:** [Architecture map](../README.md) → [Core, Storage, Hotkey, Build](README.md) → Core constants
|
||||
|
||||
**Plain English summary.** A flat list of `pub const` values that other crates reach for so the same magic numbers (sample rate, mel-spectrogram dimensions, RAM thresholds, chunk timing) are not duplicated. If you change one of these, the change propagates by recompile to every consumer.
|
||||
|
||||
## At a glance
|
||||
|
||||
- File: `crates/core/src/constants.rs` (38 LOC).
|
||||
- All items are `pub const` with concrete primitive types.
|
||||
- No external deps.
|
||||
- Consumers: slice 3 (transcription, audio capture), slice 4 (formatting paragraph break heuristic), `core::types::AudioSamples::mono_16khz` (slice 5 internal).
|
||||
|
||||
## What's in here
|
||||
|
||||
### Audio pipeline (Whisper baseline)
|
||||
|
||||
```rust
|
||||
pub const WHISPER_SAMPLE_RATE: u32 = 16_000; // crates/core/src/constants.rs:2
|
||||
pub const WHISPER_CHANNELS: u16 = 1; // crates/core/src/constants.rs:3
|
||||
```
|
||||
|
||||
Used by `AudioSamples::mono_16khz`, the audio capture worklet target rate (cross-link to [`static-assets.md`](static-assets.md)), and the Whisper engine (slice 3). The frontend `pcm-processor.js` worklet uses literal `16000` rather than importing this constant, so a change here without a coordinated worklet edit produces silently wrong audio. Documented in [`static-assets.md`](static-assets.md).
|
||||
|
||||
### Parakeet mel spectrogram (`crates/core/src/constants.rs:6-12`)
|
||||
|
||||
```rust
|
||||
pub const PARAKEET_N_FFT: usize = 512;
|
||||
pub const PARAKEET_HOP_LENGTH: usize = 160;
|
||||
pub const PARAKEET_WIN_LENGTH: usize = 400;
|
||||
pub const PARAKEET_N_MELS: usize = 80;
|
||||
pub const PARAKEET_PRE_EMPHASIS: f32 = 0.97;
|
||||
pub const PARAKEET_BLANK_TOKEN: usize = 1024;
|
||||
pub const PARAKEET_LOG_GUARD: f32 = 5.960_464_5e-8; // 2^-24
|
||||
```
|
||||
|
||||
These match the Parakeet TDT 0.6B v2 ONNX export's expected feature shape. Consumed by the Parakeet engine in slice 3. Touch only in lock-step with the model file revision pinned in [`core-model-registry.md`](core-model-registry.md).
|
||||
|
||||
### Live chunk timing (`crates/core/src/constants.rs:14-16`)
|
||||
|
||||
```rust
|
||||
pub const CHUNK_INTERVAL_MS: u64 = 3000;
|
||||
pub const MIN_CHUNK_SAMPLES: usize = 8000; // 0.5 s at 16 kHz
|
||||
```
|
||||
|
||||
Used by the live-session loop (slice 3). 3-second chunks at 16 kHz mean 48 000-sample buffers per inference call. The 8 000-sample minimum prevents very short final chunks producing garbage transcriptions when a session ends mid-buffer.
|
||||
|
||||
### Smart paragraph break (`crates/core/src/constants.rs:18-19`)
|
||||
|
||||
```rust
|
||||
pub const SMART_PARAGRAPH_GAP_SECS: f64 = 2.0;
|
||||
```
|
||||
|
||||
Consumed by `magnotia_ai_formatting::pipeline` (slice 4). When the gap between adjacent `Segment`s exceeds 2 seconds, a paragraph break is inserted. Cross-link: [Slice 4 formatting pipeline](../04-llm-formatting-mcp/README.md).
|
||||
|
||||
### History limits (`crates/core/src/constants.rs:21-22`)
|
||||
|
||||
```rust
|
||||
pub const HISTORY_MAX_ENTRIES: usize = 100;
|
||||
```
|
||||
|
||||
Used by the history page query path (slice 1 / slice 2). Today the storage layer pages with explicit `limit` arguments rather than reading this constant directly — the constant is a soft cap consumed by the frontend.
|
||||
|
||||
### RAM thresholds (`crates/core/src/constants.rs:24-28`)
|
||||
|
||||
```rust
|
||||
pub const RAM_MINIMUM_FOR_LOCAL_STT: f64 = 2.0; // GB
|
||||
pub const RAM_THRESHOLD_LIGHTWEIGHT: f64 = 4.0;
|
||||
pub const RAM_THRESHOLD_STANDARD: f64 = 8.0;
|
||||
pub const RAM_THRESHOLD_COMFORTABLE: f64 = 16.0;
|
||||
```
|
||||
|
||||
Used by the recommendation scoring path ([`core-recommendation.md`](core-recommendation.md)) and the runtime-capabilities banner (slice 2). The "comfortable" threshold drives the +10 score bonus.
|
||||
|
||||
### VAD configuration (`crates/core/src/constants.rs:30-35`)
|
||||
|
||||
```rust
|
||||
pub const VAD_SPEECH_THRESHOLD: f64 = 0.5;
|
||||
pub const VAD_MIN_SPEECH_DURATION_MS: u32 = 250;
|
||||
pub const VAD_MAX_SPEECH_DURATION_S: u32 = 30;
|
||||
pub const VAD_MIN_SILENCE_DURATION_MS: u32 = 300;
|
||||
pub const VAD_SPEECH_PAD_MS: u32 = 100;
|
||||
```
|
||||
|
||||
Defaults for the Silero VAD wrapper (slice 3). User-tunable via settings; these are the cold-start values.
|
||||
|
||||
### Model download (`crates/core/src/constants.rs:37-38`)
|
||||
|
||||
```rust
|
||||
pub const DOWNLOAD_CHUNK_BYTES: usize = 65_536; // 64 KiB
|
||||
```
|
||||
|
||||
The chunk size at which the resumable HTTP downloader emits `DownloadProgress` events. 64 KiB is fine for both the Parakeet ONNX shards and the Whisper GGML files. Consumed by the model manager paths in slices 3 and 4.
|
||||
|
||||
## Watch-outs
|
||||
|
||||
- **No grouping or namespacing.** Everything is flat. Discoverability via `grep` against the constant names.
|
||||
- **No serialisation.** These are compile-time constants. Changing one requires a rebuild; persisted user data is unaffected.
|
||||
- **`PARAKEET_BLANK_TOKEN = 1024` is the model's vocabulary index.** Hard-coded to the 0.6B v2 export. A different Parakeet variant would use a different blank index — coordinate with the registry.
|
||||
|
||||
## See also
|
||||
|
||||
- [Public types and enums](core-types-and-enums.md)
|
||||
- [Model registry](core-model-registry.md)
|
||||
- [Recommendation scoring](core-recommendation.md)
|
||||
- [Static assets and `pcm-processor.js`](static-assets.md)
|
||||
Reference in New Issue
Block a user