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

# Core app paths

> **Where you are:** [Architecture map](../README.md) → [Core, Storage, Hotkey, Build](README.md) → Core app paths

**Plain English summary.** Where Lumotia stores its files on disk. One root, derived from the OS conventions (LOCALAPPDATA on Windows, `~/Library/Application Support/Lumotia` on macOS, `$XDG_DATA_HOME/lumotia` on Linux), and named accessor methods for each subdirectory. Every other crate that needs to know "where does the database live?" reaches for `lumotia_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: `lumotia-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`

```rust
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>/lumotia.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 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%/lumotia` |
| macOS | `$HOME/Library/Application Support/Lumotia` |
| Linux | `$HOME/.lumotia` if it already exists (legacy), else `$XDG_DATA_HOME/lumotia` if set, else `$HOME/.local/share/lumotia` |
| other | `$HOME/.lumotia` |

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

### Migration idempotency — no sentinel files

There is no sentinel-file pattern. The two boot-time migrations
(`migrate_legacy_data_dir` for the legacy magnotia data dir, and
`migrate_tauri_app_data_dir_with_paths` for the Tauri bundle-identifier
move) are both idempotent by construction: each cheaply re-probes for
the legacy path via `Path::exists()` on every boot and short-circuits
on the steady state. A sentinel file would optimise that probe but is
not required for correctness, and the cost is one syscall per legacy
candidate — negligible at startup.

If a future migration needs cross-restart "this ran already" state
(e.g. a destructive one-shot reorganisation that mutates the legacy
path in place), reach for `crates/storage/src/migrations.rs`
(the SQLite schema_version table) rather than reintroducing a
filesystem sentinel — schema_version is transactional and survives
backup/restore, sentinel files don't.

## 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.
## See also

- [Storage file paths](storage-file-paths.md) — re-exports.
- [Model registry](core-model-registry.md) — model IDs feed into `speech_model_dir`.
- [Slice 2 Tauri startup](../02-tauri-runtime/README.md) — caller of `AppPaths::current()` at boot.