Heimgeist/docs/tauri-migration.md

# Tauri Migration Notes

Tauri is now Heimgeist's active desktop shell for local development. The former desktop shell runtime files and npm scripts have been removed from active development code.

## Current Development Workflow

- Primary dev command: `npm run dev`.
- Compatibility alias: `npm run dev:tauri`.
- The dev wrapper is `scripts/run-tauri-dev.cjs`.
- The wrapper starts or reuses FastAPI on `127.0.0.1:8000`, waits for `/health`, then launches Tauri.
- The Vite renderer runs on strict port `127.0.0.1:5174`.
- `npm run dev:tauri:shell` launches raw `tauri dev` when the backend lifecycle is managed separately.

The development backend is still the normal FastAPI backend started from the repository root through `scripts/run-backend.cjs`.

## User Data Continuity

- Chats continue to use `backend/app.db` through the existing FastAPI backend.
- Local RAG libraries continue to use `backend/libraries` through the existing FastAPI backend.
- No database or library state is moved, rewritten, or migrated by the Tauri shell.
- `HEIMGEIST_SETTINGS_FILE` remains an explicit shared settings override. When set, Tauri reads and writes that file directly and skips first-run import.
- Without `HEIMGEIST_SETTINGS_FILE`, Tauri stores settings in its app config `settings.json`.
- On first Tauri run only, when the Tauri settings file does not exist, Tauri attempts to import the historical Electron settings file from the platform config directory, including `Heimgeist/settings.json`.
- Existing Tauri settings are never overwritten by imported settings.

## Packaged Backend Data Paths

The backend now centralizes runtime data paths in `backend/paths.py`.

- Development remains unchanged when no internal deployment hooks are set: chat data uses `backend/app.db` and local RAG data uses `backend/libraries`.
- Packaged Tauri builds launch the backend with an app-managed data root so the backend stores data under the OS-appropriate app data directory.
- The intended packaged locations are Application Support on macOS, LocalAppData on Windows, and the XDG data directory or `~/.local/share` equivalent on Linux.
- `HEIMGEIST_DATA_DIR`, `HEIMGEIST_DB_PATH`, and `HEIMGEIST_LIB_ROOT` are internal app/sidecar plumbing hooks for packaged launchers and developer verification. They are not user-facing settings.
- Packaging does not move or migrate existing development data.

## macOS Packaged App

The first local macOS `.app` flow is implemented.

- Packaging command: `npm run package:mac`.
- Sidecar build command: `npm run build:sidecar`.
- Output app: `src-tauri/target/release/bundle/macos/Heimgeist.app`.
- `backend/sidecar_main.py` starts Uvicorn for `backend.main:app` on `127.0.0.1:8000`.
- `scripts/build-backend-sidecar.cjs` uses `backend/.venv`, installs PyInstaller there if needed, detects the Rust host target triple, and writes Tauri external binaries under `src-tauri/binaries/`.
- `src-tauri/tauri.conf.json` bundles the backend sidecar plus ffmpeg/ffprobe helper binaries through `bundle.externalBin`.
- In release builds, `src-tauri/src/main.rs` starts the bundled sidecar when no compatible Heimgeist backend is already healthy on `127.0.0.1:8000`, waits for `/health`, and fails clearly if the port is occupied by a different service.
- The Tauri shell passes `HEIMGEIST_DATA_DIR` and `HEIMGEIST_SETTINGS_FILE` to the sidecar. ffmpeg and ffprobe paths are passed when the bundled helpers exist.
- The sidecar is stopped when the Tauri app exits.

Ollama remains an external service. SearXNG remains optional.

## Desktop Bridge Surface

Renderer code should continue to call only `src/desktop/desktopApi.js` for desktop functions. That bridge owns direct access to the Tauri global and maps the renderer API to Tauri commands/events.

Current Tauri-backed desktop methods:

- `getSettings`
- `setSetting`
- `updateSettings`
- `pickPaths`
- `openPath`
- `openExternalLink`
- `onWindowFocus`
- `offWindowFocus`
- `applyUiScale`
- update/changelog placeholders

## Historical Removal Notes

This pass removed the former Electron runtime and development entry points:

- `electron/main.cjs`
- `electron/preload.cjs`
- `scripts/run-electron-dev.cjs`
- Electron npm metadata, dependencies, and scripts from `package.json`
- Electron-specific branches from `src/desktop/desktopApi.js`

The only remaining Electron references should be historical migration documentation or the Tauri first-run settings import note.

## Remaining Production-Release Tasks

- Replace update/changelog placeholders with a signed Tauri update flow or another release strategy.
- Finalize signing and notarization for macOS distribution.
- Implement updater/changelog parity or decide on a different release strategy.
- Add full Windows/Linux sidecar and bundle scripts, including platform-specific helper binaries and process shutdown behavior.
- Polish installer behavior and final bundle metadata/icons.
- Audit the PyInstaller sidecar contents and size before public release.
- Decide whether the settings route needs a dedicated Tauri window for production parity.
- Expand the basic Tauri menu if product-specific app menu actions are needed.