# Thunderbolt Tauri Desktop Application Architecture: A Deep Dive into the Rust Backend

> Explore the Tauri desktop application architecture of Thunderbolt. Discover how the Rust backend in src-tauri manages native capabilities with a centralized app builder pattern.

- Repository: [Thunderbird/thunderbolt](https://github.com/thunderbird/thunderbolt)
- Tags: architecture
- Published: 2026-04-19

---

**Thunderbolt's desktop client uses a layered Tauri 2 architecture with a Rust backend in `src-tauri` that handles platform-specific commands, plugins, and native capabilities through a centralized app builder pattern.**

The Thunderbolt email client leverages Tauri 2 to deliver a cross-platform desktop application using a Rust backend and web-based frontend. This architecture allows the Thunderbird team to share code between desktop and mobile builds while maintaining native performance. The core implementation resides in the `src-tauri` crate, organized into four distinct architectural layers that handle everything from process bootstrapping to platform-specific native code.

## Four-Layer Architecture Overview

The Tauri desktop application architecture in Thunderbolt organizes functionality into clear separation of concerns:

| Layer | Purpose | Key Implementation | Source |
|-------|---------|-------------------|--------|
| **Entry Point** | Starts the Rust process and hands control to the shared app builder. | [`main.rs`](https://github.com/thunderbird/thunderbolt/blob/main/main.rs) – calls `thunderbolt_lib::run()` | [`src-tauri/src/main.rs`](https://github.com/thunderbird/thunderbolt/blob/main/src-tauri/src/main.rs) |
| **App Builder** | Configures the Tauri `Builder` with plugins, command handlers and platform-specific tweaks. | `lib.rs::create_app()` | [`src-tauri/src/lib.rs`](https://github.com/thunderbird/thunderbolt/blob/main/src-tauri/src/lib.rs) |
| **Plugins & Platform Utilities** | Supplies native capabilities (HTTP, file-system, deep-linking, updater, etc.) and abstracts Android/iOS platform-specific APIs. | [`lib.rs`](https://github.com/thunderbird/thunderbolt/blob/main/lib.rs) registers built-in plugins and the custom `platform_utils` plugin; [`platform_utils.rs`](https://github.com/thunderbird/thunderbolt/blob/main/platform_utils.rs) implements the plugin skeleton. | [`src-tauri/src/lib.rs`](https://github.com/thunderbird/thunderbolt/blob/main/src-tauri/src/lib.rs)<br>[`src-tauri/src/platform_utils.rs`](https://github.com/thunderbird/thunderbolt/blob/main/src-tauri/src/platform_utils.rs) |
| **Command Surface** | Exposes Rust functions to the JavaScript/TypeScript front-end via Tauri's `#[command]` macros. | [`commands.rs`](https://github.com/thunderbird/thunderbolt/blob/main/commands.rs) – `toggle_dock_icon`, `set_interface_style`, `capabilities`, `start_oauth_server` | [`src-tauri/src/commands.rs`](https://github.com/thunderbird/thunderbolt/blob/main/src-tauri/src/commands.rs) |

## Bootstrapping and Entry Points

### Desktop Entry Point ([`main.rs`](https://github.com/thunderbird/thunderbolt/blob/main/main.rs))

The desktop binary entry point is intentionally minimal to maximize code reuse between platforms. Located at [`src-tauri/src/main.rs`](https://github.com/thunderbird/thunderbolt/blob/main/src-tauri/src/main.rs), it delegates immediately to the shared library:

```rust
fn main() {
    thunderbolt_lib::run();
}

```

This indirection allows the same `thunderbolt_lib` crate to power both desktop and mobile builds without duplicating initialization logic.

### Mobile Entry Point and Shared Library ([`lib.rs`](https://github.com/thunderbird/thunderbolt/blob/main/lib.rs))

For mobile targets, Tauri uses the `#[cfg_attr(mobile, tauri::mobile_entry_point)]` attribute in [`src-tauri/src/lib.rs`](https://github.com/thunderbird/thunderbolt/blob/main/src-tauri/src/lib.rs). This attribute exposes the same `run()` function as the mobile entry point while maintaining identical internal logic. The `run()` function invokes `create_app()` to configure the Tauri builder, then launches the application event loop.

## App Builder Configuration (`lib.rs::create_app`)

The `create_app()` function in [`src-tauri/src/lib.rs`](https://github.com/thunderbird/thunderbolt/blob/main/src-tauri/src/lib.rs) serves as the central configuration hub for the Tauri desktop application architecture. It orchestrates plugins, security policies, and command handlers:

```rust
fn create_app() {
    let builder = tauri::Builder::default();
    
    // Conditional native HTTP support
    #[cfg(feature = "native_fetch")]
    builder = builder.plugin(tauri_plugin_http::init());
    
    // Single-instance handling for desktop
    #[cfg(desktop)]
    builder = builder.plugin(tauri_plugin_single_instance::init());
    
    // Core plugins
    builder = builder
        .plugin(tauri_plugin_process::init())
        .plugin(tauri_plugin_fs::init())
        .plugin(tauri_plugin_opener::init())
        .plugin(tauri_plugin_os::init())
        .plugin(tauri_plugin_deep_link::init())
        .plugin(tauri_plugin_haptics::init())
        .plugin(tauri_plugin_updater::init())
        .plugin(tauri_plugin_store::init())
        .plugin(platform_utils::init());
    
    // Command registration
    builder = builder.invoke_handler(tauri::generate_handler![
        commands::toggle_dock_icon,
        commands::set_interface_style,
        commands::capabilities,
        commands::start_oauth_server,
    ]);
    
    builder
}

```

The builder pattern allows conditional compilation for platform-specific features. The `native_fetch` feature gate controls whether the HTTP plugin is active, while desktop-specific logic handles single-instance enforcement.

## Platform-Specific Abstractions

### The `platform_utils` Plugin

Thunderbolt implements a custom Tauri plugin at [`src-tauri/src/platform_utils.rs`](https://github.com/thunderbird/thunderbolt/blob/main/src-tauri/src/platform_utils.rs) to bridge Android-specific APIs. This plugin demonstrates the extensibility of the Tauri desktop application architecture when handling mobile-specific requirements.

### Android-Specific Implementations

The plugin exposes two primary commands for Android UI customization:

```rust
#[command]
pub async fn get_android_insets() -> Option<AndroidInsets> {
    // Returns insets from Android WindowInsets API
}

#[command]
pub async fn set_bar_color(color: String) -> Result<(), String> {
    // Sets Android status/navigation bar color
}

```

The plugin initialization uses conditional compilation to register the Kotlin side only on Android targets:

```rust
#[cfg(target_os = "android")]
let plugin = plugin.mobile_init(android_app);

```

This architecture ensures the JavaScript frontend can call `window.__TAURI_INVOKE__('get_android_insets')` uniformly across platforms, with the Rust layer handling platform detection.

## Command Surface ([`commands.rs`](https://github.com/thunderbird/thunderbolt/blob/main/commands.rs))

The [`src-tauri/src/commands.rs`](https://github.com/thunderbird/thunderbolt/blob/main/src-tauri/src/commands.rs) file defines the public API surface exposed to the frontend. Each function marked with `#[command]` becomes accessible via Tauri's invoke mechanism:

### `toggle_dock_icon`

Controls macOS dock visibility by modifying the application activation policy:

```rust
#[command]
pub fn toggle_dock_icon(show: bool) {
    // Implementation uses NSApplication setActivationPolicy
}

```

### `set_interface_style`

Forces iOS light or dark mode by iterating through `UIWindowScene` objects:

```rust
#[command]
pub fn set_interface_style(style: String) {
    // Applies UIUserInterfaceStyle to connected scenes
}

```

### `capabilities`

Returns runtime feature detection results, specifically whether the `native_fetch` feature is compiled:

```rust
#[command]
pub fn capabilities() -> Value {
    // Returns JSON with native_fetch: true/false
}

```

### `start_oauth_server`

Spawns a local HTTP server on loopback to capture OAuth redirects:

```rust
#[command]
pub async fn start_oauth_server(port: u16) -> Result<(), String> {
    // Binds to 127.0.0.1:port and emits "oauth-callback" event
}

```

## Configuration and Security ([`tauri.conf.json`](https://github.com/thunderbird/thunderbolt/blob/main/tauri.conf.json))

The runtime configuration at [`src-tauri/tauri.conf.json`](https://github.com/thunderbird/thunderbolt/blob/main/src-tauri/tauri.conf.json) defines the security policy and build pipeline:

- **Build hooks**: `beforeDevCommand` and `beforeBuildCommand` invoke the Bun-based frontend (`bun run dev/build`)
- **Window defaults**: Defines initial size, minimum dimensions, and starts hidden (`visible: false`)
- **Security CSP**: Whitelists `connect-src`, `img-src`, and other directives to prevent unauthorized network access
- **Plugin configuration**: Sets up deep-link schemes for mobile and updater endpoints

This configuration is compiled into the binary via `tauri::generate_context!()` and consumed during the builder initialization.

## Summary

- **Thunderbolt** uses a four-layer Tauri 2 architecture in `src-tauri` to separate entry points, app building, plugins, and command surfaces.
- **Entry point abstraction** in [`main.rs`](https://github.com/thunderbird/thunderbolt/blob/main/main.rs) delegates to `thunderbolt_lib::run()`, enabling code sharing between desktop and mobile targets.
- **Centralized configuration** in `lib.rs::create_app()` orchestrates conditional plugins like `tauri_plugin_http` (gated by `native_fetch`) and `tauri_plugin_single_instance`.
- **Platform abstraction** via the custom `platform_utils` plugin bridges Android-specific APIs while maintaining a stable Rust interface.
- **Command surface** in [`commands.rs`](https://github.com/thunderbird/thunderbolt/blob/main/commands.rs) exposes native capabilities including OAuth server management, dock icon toggling, and runtime feature detection to the frontend.

## Frequently Asked Questions

### What is the role of [`main.rs`](https://github.com/thunderbird/thunderbolt/blob/main/main.rs) in Thunderbolt's Tauri architecture?

The [`src-tauri/src/main.rs`](https://github.com/thunderbird/thunderbolt/blob/main/src-tauri/src/main.rs) file serves as the binary entry point for desktop builds. It contains minimal logic, immediately delegating to `thunderbolt_lib::run()` to launch the application. This design allows the same initialization code to power both desktop and mobile builds through conditional compilation.

### How does Thunderbolt handle platform-specific features like Android insets?

Thunderbolt implements a custom Tauri plugin called `platform_utils` located in [`src-tauri/src/platform_utils.rs`](https://github.com/thunderbird/thunderbolt/blob/main/src-tauri/src/platform_utils.rs). This plugin exposes commands like `get_android_insets` and `set_bar_color` that interface with Android's native Kotlin APIs when running on Android, while returning no-op values on other platforms. The frontend invokes these commands uniformly without platform detection logic.

### What is the purpose of the `native_fetch` feature in the Tauri configuration?

The `native_fetch` feature is a Cargo feature gate defined in [`src-tauri/Cargo.toml`](https://github.com/thunderbird/thunderbolt/blob/main/src-tauri/Cargo.toml) that conditionally compiles the `tauri_plugin_http` plugin. When enabled, the application can issue native HTTP requests from the Rust backend. The [`commands.rs`](https://github.com/thunderbird/thunderbolt/blob/main/commands.rs) file exposes a `capabilities` command that reports whether this feature is active, allowing the frontend to determine if it can use native fetch or fall back to web-based fetching.

### How does Thunderbolt manage single-instance behavior on desktop?

The application uses `tauri_plugin_single_instance` to ensure only one instance runs at a time. Configured in `lib.rs::create_app()`, this plugin detects secondary launches and focuses the existing window instead of spawning a new process. This behavior is gated behind the `#[cfg(desktop)]` conditional compilation attribute to exclude it from mobile builds where single-instance logic is handled differently by the OS.