Desktop Shell

Desktop Shell (Tauri)

As of v1.8.0, PokéTrack's primary desktop app is a native Tauri (Rust) shell that reuses the web UI verbatim — full CSS fidelity, native window chrome, a tiny binary (uses the OS WebView2, no bundled Chromium) — with zero rewrite of the Python business logic. It replaced the CustomTkinter desktop UI as the recommended way to run PokéTrack on the desktop; the CustomTkinter app (main.py, poketrack/gui/) still ships alongside it as PokeTrack.exe (see Deployment).

Why a sidecar

The Tauri app must run without Python installed, so the Flask server (run_web.py + all deps + templates/static + languages.json + the optional Rust extension) is frozen into a single poketrack-server.exe with PyInstaller (PokeTrack-server.spec) and bundled into the Tauri app as a resource. On launch, desktop/src-tauri/src/main.rs:

1. Spawns that bundled poketrack-server.exe as a sidecar process (falling back to python run_web.py in dev mode when no bundled binary exists).
2. Polls the server's port until it responds.
3. Opens a native window pointed at http://127.0.0.1:<port> — the window is the web UI (dashboard, hero, KPI cards, glass cards, dual theme — all of it).

When frozen, the server writes writable data (config, SQLite DB, image cache) to a per-user directory (%APPDATA%\PokeTrack) instead of next to the executable, since the install directory may be read-only — see poketrack/app_context.py.

Process lifetime

The sidecar is assigned to a Windows Job Object (KILL_ON_JOB_CLOSE), so it can never orphan: it exits with the app on a clean quit, a crash, or a Task-Manager kill, releasing its port immediately.

Project layout

desktop/
├── src/index.html          # tiny splash (frontendDist placeholder)
└── src-tauri/
    ├── src/main.rs          # spawn sidecar → poll port → open window; Job Object cleanup
    ├── tauri.conf.json      # NSIS installer config + bundles the server sidecar as a resource
    ├── Cargo.toml
    ├── icons/               # generated from ../../assets/icon.png
    └── binaries/            # poketrack-server.exe (built locally; git-ignored, ~40 MB)

Building locally

Prerequisites: Rust, Node, Python (with the project deps + pyinstaller), and a WebView2 runtime (preinstalled on Windows 11).

# 1. Build the server sidecar (from the repo root)
pyinstaller --noconfirm --distpath dist-server --workpath build-server PokeTrack-server.spec
cp dist-server/poketrack-server.exe desktop/src-tauri/binaries/poketrack-server.exe

# 2. Build the installer
cd desktop
npm install
npm run build            # -> src-tauri/target/release/bundle/nsis/PokeTrack_<ver>_x64-setup.exe

npm run dev runs the shell in dev mode (falls back to python run_web.py, so no sidecar build is needed to iterate).

Installing

Download PokeTrack_<version>_x64-setup.exe from Releases — an NSIS installer, per-user install, no admin rights required, and no Python needed on the target machine.

CI

desktop-shell CI (Windows) builds the Rust/Tauri shell on every push, alongside CodeQL scanning for the Python/TypeScript layers. The release.yml workflow builds and attaches the NSIS installer to GitHub Releases automatically, alongside the legacy PokeTrack.exe and the Rust native wheel — see Deployment for the full release process.

Status

Verified end-to-end from a real install: the installer installs to %LOCALAPPDATA%\PokeTrack, launches, spawns the bundled sidecar, and renders the UI with live data — no Python required. Native tray/notification integration (currently handled by the Python/web layer) is a candidate to move to Tauri's native APIs in a future release.

See Architecture for how this shell fits alongside the CustomTkinter and Flask front-ends, and Deployment for how CI assembles and releases all the build artifacts.