ADR-0003: Tauri v2 Feature-Based TypeScript UI Architecture
- Status: Accepted (Superseded in workspace layout by ADR-0004)
- Date: 2026-11-08
- Author: ngxc
- Deciders: Alolite Core Engineering
1. Context
CoreEngine (src/core/) owns the single live Session, WebSocket push loop, long-poll loop, SQLite persistence, and image/sticker decoding without any GUI framework dependency. To deliver a full-featured native WebView UI alongside the lightweight egui binary and headless --mcp server, the Tauri v2 UI must share CoreEngine directly without duplicating Zalo protocol, crypto, or SQLite logic in TypeScript.
2. Decision
-
Tauri Host (
crates/alolite-desktop/):crates/alolite-desktop/Cargo.tomldepends exclusively onalolite-coreinside the root Cargo workspace, keeping headless CLI/MCP builds free ofwebkit2gtk-4.1.TauriEventSink(crates/alolite-desktop/src/events.rs) implementsCoreEventSinkand forwardsCoreEventDtoover"core-event";crates/alolite-desktop/src/commands.rsexposes 47 thin#[tauri::command]wrappers delegating directly toCoreEngine.
-
WebView-Friendly Core Projections (
src/core/ipc.rs,settings.rs,stickers.rs):CoreImageData::to_png_data_url()encodes decoded RGBA8 buffers into compactdata:image/png;base64,...URLs before crossing IPC.CoreBootstrapSnapshothydrates initial logged-in state, threads,AppSettings, saved accounts, built-in sticker packs, and embedded PNG reaction/logo assets in one round trip.
-
Feature-Based TypeScript Frontend (
apps/desktop/src/):src/app/styles/globals.css: single-source-of-truth Tailwind CSS v4 (@tailwindcss/vite)@theme inlinetoken stylesheet with 3 layers (--rail/--sidebar/--canvasshell,shadcn/uisemantic tokens, and--bubble-in/--bubble-out/--online/--warningchat tokens) for Light (Zalo Slate) and Dark (Zinc Dark) modes.src/app/store/: pureappReducer.tsstate transitions backed byuseAppStore.ts(zustandv5 selector store).src/shared/ui/: centralizedshadcn/uicomponent library built on@radix-ui/*+class-variance-authority+clsx+tailwind-merge(button,input,badge,dialog,dropdown-menu,context-menu,popover,tabs,switch,scroll-area,tooltip,separator,Avatar,ImageViewerModal).src/features/: domain-sliced UI & logic forauth,navigation,threads(virtualized via@tanstack/react-virtual),chat,contacts,sync,settings, anddevtools.- Built with Vite 8, React 19, Tailwind CSS v4, Radix UI /
shadcn/ui, Zustand 5, TanStack Virtual 3, Lucide vector icons, and TypeScript6.0.x(>=6.0.3 <7.0.0).
-
Linux Runtime Packaging Note:
- Tauri v2 (
wry) links dynamically towebkit2gtk-4.1(2.54.xon Arch Linux, GTK3 + libsoup3). Linux distributions should ship.deb/.rpm/PKGBUILDwithwebkit2gtk-4.1declared as a package dependency (or.AppImagebundling WebKit libs), whilealolite(egui/--mcp) remains available for zero-WebKit portable.tar.gztargets.
- Tauri v2 (