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 should 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.
• This step does not move or migrate existing development data.

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.
• Package the FastAPI backend as a sidecar or equivalent production process.
• Launch the packaged backend with app-managed data paths from the Tauri shell.
• Preserve ffmpeg/ffprobe environment handling for packaged audio transcription.
• Add production backend startup health gating and shutdown behavior.
• Finalize bundle metadata, icons, signing, notarization, and installer behavior.
• 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.