Tauri & Rust Architecture

The launcher functions as a visual installer and process supervisor. It contains no standalone web frontend project; the WebView renders embedded HTML assets served via custom URI schemes outside the default tauri:// handler.

Window Management

Window	Dimensions	Behavior
main	1280×880	Resizable; initially hidden until backend signals ready
splash	800×450	Frameless, non-resizable; spawned first to report progress

Custom browser arguments applied to the WebView:

--enable-features=msWebView2EnableDraggableRegions
--disable-features=ElasticOverscroll,msWebOOUI,msPdfOOUI,msSmartScreenProtection
--no-proxy-server

• --no-proxy-server: Ensures requests to the local WebUI bypass system proxies, avoiding 127.0.0.1 routing issues.
• SmartScreen disabled: Internal embedded HTML requires no external verification.

macOS WKWebView Differences

The additionalBrowserArgs configuration is ignored by WKWebView on macOS. Handle platform divergences using #[cfg] attributes.

Custom URI Schemes

Scheme	Contents
alas-splash://	Displays initialization stages and download progress
alas-error://	Displays crash diagnostics and log inspection tools

Views are driven by embedded HTML strings coupled with splash-progress.js. State transitions push from Rust to the WebView via Tauri events; JavaScript handles presentation only.

Workflow for modifying views:

1. Update HTML templates in main.rs or modify splash-progress.js.
2. Add corresponding localization keys across all four locales/*.yml files.
3. Test layout rendering using --preview-crash.
4. Validate visual presentation across Windows, macOS, and Linux.

Startup State Machine

Idle
 → Splash (spawn frameless window)
   → Provisioning (bootstrap environment)
     → Updating (git pull + uv sync)
       → StartingBackend (free ports, spawn gui.py)
         → Waiting (poll up to 60 seconds)
           → Ready (reveal main window, inject auth session)
             → Running (system tray residency)

Failures at any stage transition to the Error state, loading alas-error:// with error details and retry actions.

WebView and Rust Communication

Direction	Mechanism	Purpose
Rust → WebView	Tauri event	Pushes progress, error states, and theme changes
WebView → Rust	#[tauri::command]	Triggers retries, opens logs, and quits app
Backend → Launcher	HTTP SSE /api/notify_stream	Streams task notifications
Backend → Launcher	HTTP /api/launcher/stream	Issues quit, restart, and autostart directives

The backend never invokes launcher functions directly; it sends commands over HTTP streams for the launcher to validate and execute. This boundary prevents the backend from terminating unintended host processes.

System Tray & Desktop Integration

Feature	Implementation
System Tray	tauri tray-icon feature
Context Menu	Show main window, restart backend, open logs directory, quit
Notifications	Windows Toast / macOS / Linux native notification daemons
Single-Instance Lock	Focuses existing window when a second executable runs
Autostart on Boot	Windows registry Run key configured with --start-minimized

Notification content arrives via SSE streams, localized to the launcher's active locale.

Localization Architecture

locales/zh-CN.yml   # Baseline reference
locales/zh-TW.yml
locales/ja.yml
locales/en.yml

Access translations via t!("module.key"), or with parameters via t!("k", p = v) referenced as %{p} in YAML files. Every added key must be populated across all four files; missing keys fall back to displaying the raw string path.

Security Boundaries

Vector	Protection Mechanism
Administrative Rights	Windows manifest enforces requireAdministrator
Self-Updates	Authenticated over mTLS client certificates; secrets excluded from repository
Local WebUI Access	Enforces --no-proxy-server and injects single-use login tokens
Process Isolation	CREATE_NO_WINDOW prevents rogue console popups
Process Cleanup	Combines environment tags with Windows Job Objects to clean process trees on exit
Logging Hygiene	Authentication tokens and credentials are scrubbed from log outputs

Implementation Pitfalls

Anti-Pattern	Reason
Relying on additionalBrowserArgs on macOS	Unsupported by WKWebView
Logging via println!	Invisible in windowed builds and omitted from log files
Forcibly killing the backend directly	Bypasses Job Object and process group cleanup, creating orphan workers
Updating only one localization YAML	Other locales will display raw translation keys
Hardcoding the uv path	Must fall back to system PATH if internal uv binary is missing

Related Documentation

• Backend Process LifecycleJob Objects, breakaway rules, and process cleanup
• Update Pipelines & MirrorsGit pull retries, uv sync, and mTLS verification
• Build & ReleaseCross-platform packaging matrix