tauri-core-architecture

name	tauri-core-architecture
description	Use when creating new Tauri 2 apps, understanding project structure, or reasoning about the component model. Prevents mixing Tauri 1.x architecture assumptions with the v2 multi-webview and capability-based model. Covers Rust backend structure, webview layer, IPC bridge model, process model, project layout, and type hierarchy. Keywords: tauri architecture, project structure, IPC bridge, webview layer, process model, Rust backend.
license	MIT
compatibility	Designed for Claude Code. Requires Tauri 2.x with Rust and TypeScript.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

tauri-core-architecture

Quick Reference

Architecture Layers (Tauri 2.x)

Layer	Technology	Location	Role
Rust Backend	Rust + Tokio	src-tauri/src/	Application logic, system access, state management
Webview Layer	Platform-native webview	Embedded	Renders HTML/CSS/JS frontend
IPC Bridge	JSON-serialized messages	Internal	Connects frontend to backend via invoke() and events
Plugin System	Rust crate + npm package	Cargo.toml + package.json	Extends capabilities (fs, dialogs, HTTP, etc.)
Permission System	Capabilities + permissions	src-tauri/capabilities/	Fine-grained access control (replaces v1 allowlist)

Platform Webview Engines

Platform	Webview Engine
Windows	WebView2 (Chromium-based)
macOS	WKWebView
Linux	WebKitGTK
iOS	WKWebView
Android	Android WebView

Key Dependencies

Package	Type	Purpose
@tauri-apps/cli	devDependency (npm)	CLI tooling for dev/build
@tauri-apps/api	dependency (npm)	Frontend API for invoke, events, paths
tauri	dependency (Cargo)	Core Rust framework
tauri-build	build-dependency (Cargo)	Build script helpers
serde + serde_json	dependency (Cargo)	Serialization for IPC

Critical Warnings

NEVER block the main thread with synchronous I/O in commands -- ALWAYS use async for file, network, or long-running operations. Blocking freezes the entire UI.

NEVER call .invoke_handler() more than once on Builder -- only the LAST call takes effect. Put ALL commands in a single generate_handler![] macro.

NEVER mark command functions as pub when defined directly in lib.rs -- the glue code generation prevents it. Move commands to a separate module if they need to be public.

NEVER wrap managed state in Arc -- Tauri wraps state in Arc internally. Using app.manage(Arc::new(data)) adds a redundant layer.

NEVER use &str in async command parameters -- borrowed references do not work with async command spawning. ALWAYS use String instead.

NEVER use State<'_, T> when you registered Mutex<T> -- this causes a runtime panic, not a compile error. ALWAYS match the exact registered type: State<'_, Mutex<T>>.

---

Process Model

Tauri 2 uses a two-process architecture:

Main Process (Rust)

• Runs the Rust backend on the main thread + Tokio async runtime
• Has full system access (filesystem, network, OS APIs)
• Manages application lifecycle, windows, menus, tray icons
• Exposes #[tauri::command] functions as IPC endpoints
• Manages state via app.manage() with Arc-wrapped storage

Webview Process (Frontend)

• Runs in a platform-native webview (NOT Electron/Chromium bundle)
• Renders HTML/CSS/JS like a browser tab
• Communicates with Rust ONLY through the IPC bridge
• Has NO direct system access -- all system operations go through invoke()
• Event listeners enable bidirectional pub/sub messaging

IPC Bridge

The bridge between processes uses JSON-serialized messages:

Frontend                          Rust Backend
   |                                   |
   |--- invoke('cmd', {args}) -------->|  (JSON request)
   |                                   |--- execute command
   |<-- Result<T, E> (JSON) ----------|  (JSON response)
   |                                   |
   |--- emit('event', payload) ------->|  (event pub/sub)
   |<-- emit('event', payload) --------|  (event pub/sub)
   |                                   |
   |<-- Channel.send(data) -----------|  (streaming)

• invoke() sends a JSON object with camelCase keys; Rust receives snake_case parameters
• Events use Serialize + Clone payloads
• Channels enable streaming multiple messages from Rust to JS
• Binary data can bypass JSON via tauri::ipc::Response

---

Project Structure

my-tauri-app/
├── src/                        # Frontend source (React/Vue/Svelte/vanilla)
│   ├── index.html
│   ├── main.ts
│   └── styles.css
├── src-tauri/                  # Rust backend
│   ├── src/
│   │   ├── lib.rs              # Main app logic (mobile entry point)
│   │   └── main.rs             # Desktop entry point (calls lib.rs)
│   ├── capabilities/           # Permission capability files (JSON/TOML)
│   │   └── default.json        # Default capabilities
│   ├── permissions/            # Custom command permissions (TOML only)
│   ├── icons/                  # Application icons (all required sizes)
│   ├── gen/                    # Generated files (DO NOT edit manually)
│   │   └── schemas/
│   │       ├── desktop-schema.json
│   │       ├── mobile-schema.json
│   │       └── remote-schema.json
│   ├── Cargo.toml              # Rust dependencies
│   ├── Cargo.lock              # Deterministic build lock
│   ├── tauri.conf.json         # Main configuration
│   ├── build.rs                # Cargo build script
│   └── .taurignore             # Exclude files from dev watcher
├── package.json                # Frontend dependencies
├── tsconfig.json               # TypeScript config (if applicable)
└── vite.config.ts              # Bundler config (if Vite)

Source Control Rules

• ALWAYS commit: src-tauri/Cargo.lock (deterministic builds)
• ALWAYS ignore: src-tauri/target/ (build artifacts)
• NEVER edit: src-tauri/gen/ (auto-generated schemas)

Entry Point Pattern (Tauri 2.x)

Desktop and mobile share logic through lib.rs:

// src-tauri/src/lib.rs
#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![/* commands */])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

// src-tauri/src/main.rs (desktop only)
#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
fn main() {
    app_lib::run();
}

ALWAYS use the lib.rs + main.rs split pattern for Tauri 2 -- this is required for mobile support and is the standard project layout.

---

Type Hierarchy

Core Types

Type	Description	Traits
App	Full application instance (only in setup())	Manager, Emitter, Listener
AppHandle	Lightweight clone-safe handle to the app	Manager, Emitter, Listener, Clone + Send + Sync
WebviewWindow	Combined window + webview (most common)	Manager, Emitter, Listener
Window	OS-level window (without webview)	Manager, Emitter, Listener
Webview	Webview inside a window	Manager, Emitter, Listener
State<'_, T>	Managed state accessor in commands	--
Builder	Application configuration builder	--

The Manager Trait

The Manager trait is the unifying interface. It is implemented by App, AppHandle, Webview, WebviewWindow, and Window. Key methods:

Method	Return Type	Purpose
app_handle()	&AppHandle<R>	Get the AppHandle
config()	&Config	Access tauri.conf.json
state::<T>()	State<'_, T>	Access managed state
try_state::<T>()	Option<State<'_, T>>	Access state without panic
manage(state)	bool	Register new state
get_webview_window(label)	Option<WebviewWindow<R>>	Get window by label
webview_windows()	HashMap<String, WebviewWindow<R>>	Get all windows
get_window(label)	Option<Window<R>>	Get OS window by label
path()	&PathResolver<R>	Access path resolver
package_info()	&PackageInfo	Get package metadata

The Emitter Trait

Method	Purpose
emit(event, payload)	Broadcast to ALL targets
emit_to(target, event, payload)	Emit to a specific target
emit_filter(event, payload, filter_fn)	Emit to targets matching a filter
emit_str(event, json_string)	Emit with pre-serialized JSON

The Listener Trait

Method	Purpose
listen(event, handler)	Listen for events (returns EventId)
once(event, handler)	Listen once, auto-remove after first event
unlisten(id)	Remove a listener
listen_any(event, handler)	Listen from any source

Runtime Generic

Most types are generic over R: Runtime. With the default wry feature, R resolves to Wry. Use the generic form in plugins or for test mocking:

#[tauri::command]
async fn my_command<R: Runtime>(
    app: AppHandle<R>,
    window: WebviewWindow<R>,
) -> Result<(), String> {
    Ok(())
}

---

Builder Pattern

The Builder is the single entry point for configuring a Tauri application:

tauri::Builder::default()
    .manage(MyState::default())                              // state
    .plugin(tauri_plugin_shell::init())                      // plugins
    .invoke_handler(tauri::generate_handler![cmd1, cmd2])    // commands
    .setup(|app| {                                           // init hook
        let handle = app.handle().clone();
        // app is &mut App -- full access, runs once
        Ok(())
    })
    .on_window_event(|window, event| { /* ... */ })          // window events
    .on_menu_event(|app, event| { /* ... */ })               // menu events
    .menu(|app| { /* build menu */ })                        // app menu
    .run(tauri::generate_context!())
    .expect("error running app");

Builder Method Reference

Method	Purpose
manage(T)	Register managed state
plugin(P)	Register a plugin
invoke_handler(F)	Register ALL command handlers
setup(F)	App initialization hook
menu(F)	Set the application menu
on_menu_event(F)	Menu event handler
on_window_event(F)	Window event handler
on_webview_event(F)	Webview event handler
on_page_load(F)	Page load handler
on_tray_icon_event(F)	Tray icon event handler
build(Context)	Build without running (returns App)
run(Context)	Build and run the app
any_thread(self)	Allow running on any thread

---

Frontend API Overview

API Area	Key Functions	Import Path
Commands	invoke<T>(), Channel<T>	@tauri-apps/api/core
Events	listen(), emit(), emitTo(), once()	@tauri-apps/api/event
Windows	getCurrentWindow(), getAllWindows()	@tauri-apps/api/window
Webviews	getCurrentWebview()	@tauri-apps/api/webview
Paths	appDataDir(), join(), BaseDirectory	@tauri-apps/api/path
Utilities	convertFileSrc(), isTauri()	@tauri-apps/api/core
Testing	mockIPC(), mockWindows(), clearMocks()	@tauri-apps/api/mocks

---

Reference Links

• references/methods.md -- API signatures for App, AppHandle, Manager, Runtime, Webview, WebviewWindow
• references/examples.md -- Working code examples verified against Tauri 2.x documentation
• references/anti-patterns.md -- What NOT to do, with WHY explanations

Official Sources

• https://v2.tauri.app/develop/
• https://docs.rs/tauri/latest/tauri/
• https://v2.tauri.app/reference/javascript/api/
• https://v2.tauri.app/start/create-project/