Lumotia/docs/architecture-map/05-core-storage-hotkey-build/core-paths.md

name, type, slice, last_verified

name	type	slice	last_verified
Core app paths	architecture-map-page	05-core-storage-hotkey-build	2026/05/09

Core app paths

Where you are: Architecture map → Core, Storage, Hotkey, Build → Core app paths

Plain English summary. Where Magnotia stores its files on disk. One root, derived from the OS conventions (LOCALAPPDATA on Windows, ~/Library/Application Support/Magnotia on macOS, $XDG_DATA_HOME/magnotia on Linux), and named accessor methods for each subdirectory. Every other crate that needs to know "where does the database live?" reaches for magnotia_core::paths::AppPaths::current().

At a glance

• File: crates/core/src/paths.rs (125 LOC).
• External deps: standard library only.
• Public surface: AppPaths (struct), app_paths, app_data_dir.
• Consumers: magnotia-storage::file_storage (re-exports the path helpers), the Tauri startup code (slice 2), the model manager (slices 3 + 4), the diagnostic-report bundler (slice 2).

What's in here

AppPaths — crates/core/src/paths.rs:6

pub struct AppPaths { app_data_dir: PathBuf }

impl AppPaths {
    pub fn current() -> Self;                         // resolves at construction
    pub fn app_data_dir(&self) -> PathBuf;
    pub fn database_path(&self) -> PathBuf;           // <root>/magnotia.db
    pub fn recordings_dir(&self) -> PathBuf;          // <root>/recordings
    pub fn crashes_dir(&self) -> PathBuf;             // <root>/crashes
    pub fn logs_dir(&self) -> PathBuf;                // <root>/logs
    pub fn diagnostic_reports_dir(&self) -> PathBuf;  // <root>/diagnostic-reports
    pub fn models_dir(&self) -> PathBuf;              // <root>/models
    pub fn speech_model_dir(&self, id: &ModelId) -> PathBuf;  // <root>/models/<id>
    pub fn llm_models_dir(&self) -> PathBuf;          // <root>/models/llm
    pub fn migration_sentinel(&self, name: &str) -> PathBuf;  // <root>/.<name>.sentinel
}

pub fn app_paths() -> AppPaths;
pub fn app_data_dir() -> PathBuf;

Root resolution — crates/core/src/paths.rs:66

The resolve_app_data_dir function picks the root by cfg(target_os = ...):

OS	Root
Windows	%LOCALAPPDATA%/magnotia
macOS	$HOME/Library/Application Support/Magnotia
Linux	$HOME/.magnotia if it already exists (legacy), else $XDG_DATA_HOME/magnotia if set, else $HOME/.local/share/magnotia
other	$HOME/.magnotia

The Linux legacy-path branch keeps existing users on ~/.magnotia (early dogfooding default) without forcing a migration when the canonical XDG location is preferred.

Sentinel files — crates/core/src/paths.rs:53

migration_sentinel(name) -> <root>/.<name>.sentinel. Used for one-shot data migrations outside the SQLite schema (for example, a one-off file-system reorganisation). The pattern is: write the sentinel after the migration runs successfully; check for the sentinel on next startup; skip the migration if the sentinel exists.

Data flow / contract

• All paths are derived from a single root. Changing resolve_app_data_dir once moves every downstream file. Tested at paths.rs:111.
• Path resolution is pure: only reads env vars (HOME, LOCALAPPDATA, XDG_DATA_HOME) plus Path::exists for the Linux legacy probe.
• AppPaths::current() does not create directories. Callers that need a directory to exist call std::fs::create_dir_all at write time. The storage init function does this for the database parent (crates/storage/src/database.rs:10).

Tests

crates/core/src/paths.rs:104-125:

• derives_all_paths_from_one_base — verifies that database_path, speech_model_dir(<id>), and llm_models_dir are all rooted at the same app_data_dir.

Watch-outs

• std::env::var(...).unwrap_or_else(|_| "/tmp".to_string()) is the fallback for missing HOME. Should never trigger in practice; defensive.
• AppPaths::current() reads env vars at every call. Cheap, but repeated calls are wasteful. Slice 2 caches a OnceLock<AppPaths> so the value is resolved once at startup.
• No Windows fallback for missing LOCALAPPDATA. Falls through to . (current working directory). On a misconfigured Windows host this could write the database next to the binary. Not great; the impact is limited to first-run scenarios where the env is broken.
• Sentinel files are hidden on Unix (.<name>.sentinel) but visible on Windows. Acceptable; sentinels live alongside magnotia.db so the user sees both.

See also

• Storage file paths — re-exports.
• Model registry — model IDs feed into speech_model_dir.
• Slice 2 Tauri startup — caller of AppPaths::current() at boot.