12 Cross Platform Client Architecture

12 — Cross-Platform Client Architecture

Corresponding Specifications: sys-arch/ui-ux-01-product-foundation-cross-platform-interaction-architecture.md, sys-arch/ui-ux-02-desktop-dioxus-app-shell-navigation-window-architecture.md, sys-arch/ui-ux-03-android-jetpack-compose-app-shell-navigation-lifecycle-architecture.md
Key Modules: crates/siar-ui-state, apps/desktop, apps/android

---

1. Unified Core & Native Shell Strategy

SIAR uses a Single Core, Native Presentation architectural model:

+-------------------------------------------------------------------------------+
|             Desktop UI (Dioxus 0.7)            Android UI (Jetpack Compose)   |
|            Rust-Native Cross-Platform                Kotlin Material 3        |
+------------------------------------+------------------------------------------+
                                     | (JNI Bridge / Direct In-Process Memory)
+------------------------------------v------------------------------------------+
|                  SIAR Reactive UI State Engine (siar-ui-state)                 |
|       - Unidirectional Data Flow (UDF)      - Optimistic UI Mutators          |
|       - Caching & View State Slices         - Subscription Event Bus          |
+------------------------------------+------------------------------------------+
                                     |
+------------------------------------v------------------------------------------+
|                       Underlying Rust Workspace Services                      |
| (siar-storage, siar-messaging, siar-routing, siar-crypto, siar-calls)         |
+-------------------------------------------------------------------------------+

Core Invariants

1. Zero Business Logic in UI: All encryption, routing, validation, database operations, and state machine transitions execute strictly inside the Rust workspace.
2. Deterministic UI State: The UI is a pure projection of the reactive state models exposed by siar-ui-state.
3. Instant Responsiveness: Optimistic updates render message bubbles and UI interactions in $< 16\text{ms}$ (60 fps), updating delivery ticks asynchronously as network events arrive.

---

2. Desktop Shell: Dioxus 0.7 Architecture

The desktop application (apps/desktop) is written entirely in modern Rust using Dioxus 0.7:

#[component]
pub fn AppShell() -> Element {
    let active_tab = use_signal(|| NavigationTab::Inbox);
    let system_health = use_signal(|| MeshHealthStatus::Healthy);

    rsx! {
        div { class: "app-container dark-theme",
            SidebarNavigation { active_tab }
            MainContentSplitView { active_tab }
            StatusBarMeshTelemetry { system_health }
        }
    }
}

Desktop Capabilities

• Multi-Pane Responsive Layout: Collapsible sidebar, virtualized conversation stream, detail inspection sidebar.
• System Tray & Hotkeys: Native window minimizing to notification tray with global emergency shortcut keys.
• Hardware Acceleration: GPU-accelerated rendering with low idle RAM footprint ($< 60\text{ MB}$).

---

3. Android Shell: Jetpack Compose & JNI Glue

The Android application (apps/android) combines modern Jetpack Compose Kotlin UI with native Rust performance:

[Kotlin Jetpack Compose ViewModels]
                 |
                 v
[SiarNativeBridge (JNI Interface)]
                 |
                 v
[crates/siar-ui-state & Rust Core Engine]

Android Lifecycle & Service Management

• MeshForegroundService: Maintains persistent low-power BLE advertising/scanning and Wi-Fi Direct listening when the screen is locked.
• WakeLock Management: Partitions wakeups into short, bounded micro-windows ($< 250\text{ms}$) to preserve battery longevity while maintaining mesh routing presence.
• Material You Dynamic Theming: Adaptive color palette conforming to system dark mode and user accessibility settings.