understanding-tauri-architecture

What this skill does

# Tauri Architecture

Tauri is a polyglot toolkit for building desktop applications that combines a Rust backend with HTML/CSS/JavaScript rendered in a native webview. This document covers the fundamental architecture concepts.

## Architecture Overview

```
+------------------------------------------------------------------+
|                        TAURI APPLICATION                         |
+------------------------------------------------------------------+
|                                                                  |
|  +---------------------------+    +---------------------------+  |
|  |      FRONTEND (Shell)     |    |     BACKEND (Core)        |  |
|  |---------------------------|    |---------------------------|  |
|  |                           |    |                           |  |
|  |  HTML / CSS / JavaScript  |    |        Rust Code          |  |
|  |  (or any web framework)   |    |    (tauri crate + app)    |  |
|  |                           |    |                           |  |
|  |  - React, Vue, Svelte,    |    |  - System access          |  |
|  |    Solid, etc.            |    |  - File operations        |  |
|  |  - Standard web APIs      |    |  - Native features        |  |
|  |  - Tauri JS API           |    |  - Plugin system          |  |
|  |                           |    |                           |  |
|  +-------------+-------------+    +-------------+-------------+  |
|                |                                |                 |
|                |       IPC (Message Passing)    |                 |
|                +<------------------------------->+                |
|                |     Commands & Events          |                 |
|                                                                  |
|  +------------------------------------------------------------+  |
|  |                    WEBVIEW (TAO + WRY)                     |  |
|  |------------------------------------------------------------|  |
|  |  - Platform-native webview (not bundled)                   |  |
|  |  - Windows: WebView2 (Edge/Chromium)                       |  |
|  |  - macOS: WKWebView (Safari/WebKit)                        |  |
|  |  - Linux: WebKitGTK                                        |  |
|  +------------------------------------------------------------+  |
|                                                                  |
+------------------------------------------------------------------+
                                |
                                v
+------------------------------------------------------------------+
|                     OPERATING SYSTEM                             |
|  - Windows, macOS, Linux, iOS, Android                          |
+------------------------------------------------------------------+
```

## Core vs Shell Design

Tauri follows a **Core-Shell architecture** where the application is split into two distinct layers:

### The Core (Rust Backend)

The Core is the Rust-based backend that handles all system-level operations:

- **System access**: File system, network, processes
- **Native features**: Notifications, dialogs, clipboard
- **Security enforcement**: Permission validation, capability checking
- **Plugin management**: Extending functionality through plugins
- **App lifecycle**: Window management, updates, configuration

The Core NEVER exposes direct system access to the frontend. All interactions go through validated IPC channels.

### The Shell (Frontend)

The Shell is the user interface layer rendered in a webview:

- **Web technologies**: HTML, CSS, JavaScript/TypeScript
- **Framework agnostic**: Works with React, Vue, Svelte, Solid, or vanilla JS
- **Sandboxed execution**: Runs in the webview's security sandbox
- **Tauri API access**: Calls backend through `@tauri-apps/api`

## Key Ecosystem Components

### tauri Crate

The central orchestrator that:
- Reads `tauri.conf.json` at compile time
- Manages script injection into the webview
- Hosts the system interaction API
- Handles application updates
- Integrates runtimes, macros, and utilities

### tauri-runtime

The glue layer between Tauri and lower-level webview libraries. Abstracts platform-specific webview interactions so the rest of Tauri can remain platform-agnostic.

### tauri-macros and tauri-codegen

Generate compile-time code for:
- Command handlers (`#[tauri::command]`)
- Context and configuration parsing
- Asset embedding and compression

### TAO (Window Management)

Cross-platform window creation library (forked from Winit):
- Creates and manages application windows
- Handles menu bars and system trays
- Supports Windows, macOS, Linux, iOS, Android

### WRY (WebView Rendering)

Cross-platform WebView rendering library:
- Abstracts webview implementations per platform
- Handles webview-to-native communication
- Manages JavaScript evaluation and event bridging

## Webview Integration

Tauri uses the **operating system's native webview** rather than bundling a browser engine:

```
+-------------------+---------------------------+
|     Platform      |        WebView Engine     |
+-------------------+---------------------------+
| Windows           | WebView2 (Edge/Chromium)  |
| macOS             | WKWebView (Safari/WebKit) |
| Linux             | WebKitGTK                 |
| iOS               | WKWebView                 |
| Android           | Android WebView           |
+-------------------+---------------------------+
```

### Benefits of Native WebViews

1. **Smaller binary size**: No bundled browser engine (~600KB vs ~150MB)
2. **Security**: OS vendors patch webview vulnerabilities faster than app developers can rebuild
3. **Performance**: Native integration with the operating system
4. **Consistency**: Users see familiar rendering behavior

### Considerations

- Slight rendering differences between platforms
- Feature availability depends on OS webview version
- Testing should cover all target platforms

## Inter-Process Communication (IPC)

Tauri implements **Asynchronous Message Passing** for communication between frontend and backend. This is safer than shared memory because the Core can reject malicious requests.

### IPC Flow Diagram

```
+------------------+                      +------------------+
|    Frontend      |                      |   Rust Backend   |
|   (JavaScript)   |                      |     (Core)       |
+--------+---------+                      +--------+---------+
         |                                         |
         |  1. invoke('command', {args})           |
         +---------------------------------------->|
         |                                         |
         |     [Request serialized as JSON-RPC]    |
         |                                         |
         |                    2. Validate request  |
         |                    3. Check permissions |
         |                    4. Execute command   |
         |                                         |
         |  5. Return Result<T, E>                 |
         |<----------------------------------------+
         |                                         |
         |     [Response serialized as JSON]       |
         |                                         |
```

### Two IPC Primitives

#### Commands (Request-Response)

Type-safe, frontend-to-backend function calls:

```rust
// Rust backend
#[tauri::command]
fn greet(name: String) -> String {
    format!("Hello, {}!", name)
}

// Register in builder
tauri::Builder::default()
    .invoke_handler(tauri::generate_handler![greet])
```

```javascript
// JavaScript frontend
import { invoke } from '@tauri-apps/api/core';

const greeting = await invoke('greet', { name: 'World' });
console.log(greeting); // "Hello, World!"
```

Key characteristics:
- Built on JSON-RPC protocol
- All arguments must be JSON-serializable
- Returns a Promise that resolves with the result
- Supports async Rust functions
- Can access app state, window handle, etc.