mirror of
https://github.com/tinyhumansai/openhuman.git
synced 2026-07-30 15:03:57 +00:00
Steven Enamakel
c46cf127e9
- Changed all references of the deep link scheme in documentation and code to `alphahuman://` to align with the new branding. - Updated the Telegram login flow documentation to reflect the new deep link handling. - Adjusted various files to ensure consistency in the authentication process across platforms. This update enhances the clarity and branding of the authentication flow for the desktop application.
151 lines
5.3 KiB
Markdown
151 lines
5.3 KiB
Markdown
# Rust Backend Architecture
|
|
|
|
## Overview
|
|
|
|
The Tauri Rust backend provides native functionality for the AlphaHuman desktop application:
|
|
|
|
- System tray with background execution
|
|
- Deep link authentication
|
|
- Secure session storage (OS Keychain)
|
|
- Socket.io state management
|
|
- Native notifications
|
|
- Window management
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
src-tauri/src/
|
|
├── lib.rs # Entry point, plugin registration, tray setup
|
|
├── main.rs # Binary entry (desktop)
|
|
├── commands/ # Tauri IPC commands
|
|
│ ├── mod.rs
|
|
│ ├── auth.rs # Authentication commands
|
|
│ ├── socket.rs # Socket state commands
|
|
│ ├── telegram.rs # Telegram login commands
|
|
│ └── window.rs # Window management commands
|
|
├── services/ # Background services
|
|
│ ├── mod.rs
|
|
│ ├── session_service.rs # Secure session storage (keychain)
|
|
│ ├── socket_service.rs # Socket.io state management
|
|
│ └── notification_service.rs # Native notifications
|
|
├── models/ # Data structures
|
|
│ ├── mod.rs
|
|
│ ├── auth.rs # Auth types (Session, User)
|
|
│ └── socket.rs # Socket types (ConnectionStatus)
|
|
└── utils/ # Configuration and helpers
|
|
├── mod.rs
|
|
└── config.rs # Environment configuration
|
|
```
|
|
|
|
## Key Components
|
|
|
|
### lib.rs - Application Entry
|
|
|
|
The main entry point that:
|
|
|
|
1. Registers Tauri plugins (opener, deep-link, autostart, notification)
|
|
2. Sets up system tray with Show/Hide and Quit menu
|
|
3. Handles macOS-specific window close behavior (minimize to tray)
|
|
4. Registers all IPC commands
|
|
|
|
### Commands Layer
|
|
|
|
Commands are exposed to the frontend via Tauri's IPC:
|
|
|
|
| Module | Commands | Purpose |
|
|
| ---------- | --------------------------------------------------- | -------------- |
|
|
| `auth` | `exchange_token`, `get_auth_state`, `logout`, etc. | Authentication |
|
|
| `socket` | `socket_connect`, `report_socket_connected`, etc. | Socket state |
|
|
| `telegram` | `start_telegram_login` | Telegram OAuth |
|
|
| `window` | `show_window`, `hide_window`, `toggle_window`, etc. | Window control |
|
|
|
|
### Services Layer
|
|
|
|
Singleton services providing background functionality:
|
|
|
|
| Service | Purpose | Storage |
|
|
| --------------------- | -------------------------- | --------------- |
|
|
| `SessionService` | Secure auth token storage | OS Keychain |
|
|
| `SocketService` | Socket.io state management | Memory + Events |
|
|
| `NotificationService` | Native notifications | N/A |
|
|
|
|
## Architecture Decisions
|
|
|
|
### Socket.io Strategy
|
|
|
|
The frontend maintains the actual Socket.io connection, while Rust:
|
|
|
|
1. Stores connection parameters
|
|
2. Tracks connection state
|
|
3. Emits events to coordinate with frontend
|
|
4. Ensures socket stays connected when window is hidden
|
|
|
|
This approach is necessary because:
|
|
|
|
- Rust's Socket.io libraries have API compatibility issues
|
|
- The WebView maintains state when hidden (unlike browser tabs)
|
|
- Frontend JavaScript is better suited for Socket.io's event-driven model
|
|
|
|
### Keychain Storage
|
|
|
|
Session tokens are stored in the OS keychain for security:
|
|
|
|
- **macOS**: Keychain
|
|
- **Windows**: Credential Manager
|
|
- **Linux**: Secret Service
|
|
|
|
### Event Bridge Pattern
|
|
|
|
Rust communicates with the frontend via Tauri events:
|
|
|
|
```rust
|
|
// Rust emits event
|
|
app.emit("socket:should_connect", json!({ "backendUrl": url, "token": token }))
|
|
|
|
// Frontend listens
|
|
listen("socket:should_connect", (event) => {
|
|
socketService.connect(event.payload.backendUrl, event.payload.token);
|
|
});
|
|
```
|
|
|
|
## Plugin Dependencies
|
|
|
|
| Plugin | Version | Purpose |
|
|
| --------------------------- | ------- | --------------------------- |
|
|
| `tauri-plugin-opener` | 2 | Open URLs in browser |
|
|
| `tauri-plugin-deep-link` | 2.0.0 | Handle `alphahuman://` URLs |
|
|
| `tauri-plugin-autostart` | 2 | Launch at login |
|
|
| `tauri-plugin-notification` | 2 | Native notifications |
|
|
|
|
## Cargo Dependencies
|
|
|
|
| Crate | Purpose |
|
|
| --------------------- | --------------------------------------- |
|
|
| `tauri` | Core framework with tray and macOS APIs |
|
|
| `serde`, `serde_json` | Serialization |
|
|
| `reqwest` | HTTP client |
|
|
| `tokio` | Async runtime |
|
|
| `keyring` | Secure credential storage |
|
|
| `once_cell` | Lazy static singletons |
|
|
| `parking_lot` | Fast mutexes |
|
|
| `log`, `env_logger` | Logging |
|
|
|
|
## Platform-Specific Behavior
|
|
|
|
### macOS
|
|
|
|
- Window close button hides instead of quitting
|
|
- Dock icon click shows window
|
|
- LaunchAgent for autostart
|
|
- Keychain for secure storage
|
|
|
|
### Windows/Linux
|
|
|
|
- Deep link registration at runtime
|
|
- Platform-specific credential storage
|
|
- Registry (Windows) or desktop file (Linux) autostart
|
|
|
|
---
|
|
|
|
_Next: [Commands Reference](./02-commands.md)_
|