# DETAILS.md 🔍 **Powered by [Detailer](https://detailer.ginylil.com)** - Smart agent-compatible documentation --- ## 1. Project Overview ### Purpose & Domain This project is a comprehensive, cross-platform remote desktop and collaboration system primarily implemented in Rust with Flutter-based UI components. It enables users to remotely access, control, and manage devices securely and efficiently, supporting multimedia streaming (video/audio), file transfer, clipboard synchronization, and multi-session management. ### Problem Solved - Provides seamless remote desktop access across Windows, macOS, Linux, Android, iOS, and Web platforms. - Supports NAT traversal, relay servers, and peer-to-peer connections for robust connectivity. - Enables secure file transfer, clipboard sharing, and multi-user collaboration. - Offers extensible plugin architecture for customization and feature expansion. - Facilitates privacy modes and virtual display management for enhanced security and usability. ### Target Users & Use Cases - IT administrators managing remote systems. - End-users requiring remote access to personal or work devices. - Developers and integrators extending remote desktop capabilities. - Organizations deploying secure remote collaboration tools. - Users needing cross-platform remote desktop and file sharing. ### Core Business Logic & Domain Models - **Connection Management:** Peer-to-peer and relay-based remote sessions (`src/client.rs`, `src/rendezvous_mediator.rs`). - **Media Streaming:** Video/audio capture, encoding, decoding, and rendering (`libs/scrap/`, `src/server.rs`). - **Clipboard & File Transfer:** Cross-platform clipboard synchronization and file transfer protocols (`libs/clipboard/`, `src/clipboard.rs`). - **Privacy & Security:** Privacy modes, secure authentication, and update mechanisms (`src/privacy_mode.rs`, `src/updater.rs`). - **Plugin System:** Dynamic plugin loading, configuration, and event handling (`src/plugin/`). - **UI Layer:** Flutter-based UI for desktop, mobile, and web (`flutter/lib/`), with native platform integrations (`src/ui.rs`, `flutter/windows/runner`). --- ## 2. Architecture and Structure ### High-Level Architecture - **Cross-Platform Core:** Rust-based core logic handling networking, media, clipboard, and system integration. - **UI Layer:** Flutter-based UI supporting desktop, mobile, and web platforms, with native bridges and plugins. - **Platform Abstraction:** Modular platform-specific code under `src/platform/`, `libs/enigo/`, `libs/clipboard/`, and `libs/scrap/`. - **Plugin System:** Dynamic plugin management with IPC and native handlers. - **Build & Deployment:** Multi-platform build scripts, CI/CD workflows, and packaging under `.github/workflows/`, `build.py`, `libs/portable/`. --- ### Complete Repository Structure ``` . ├── .cargo/ │ └── config.toml ├── .claude/ │ └── commands/ │ └── reflection.md ├── .github/ (19 items) │ ├── ISSUE_TEMPLATE/ │ ├── patches/ │ ├── workflows/ (11 items) │ ├── FUNDING.yml │ └── dependabot.yml ├── appimage/ ├── docs/ (62 items) ├── examples/ ├── fastlane/ (14 items) ├── flatpak/ ├── flutter/ (314 items) │ ├── android/ │ ├── assets/ │ ├── ios/ │ ├── lib/ (132 items) │ │ ├── common/ │ │ ├── desktop/ │ │ ├── mobile/ │ │ ├── models/ │ │ ├── native/ │ │ ├── plugin/ │ │ ├── utils/ │ │ └── web/ │ ├── linux/ │ ├── .gitattributes │ ├── .gitignore │ ├── .metadata │ ├── README.md │ └── ... ├── libs/ (174 items) │ ├── clipboard/ │ ├── enigo/ │ ├── portable/ │ ├── remote_printer/ │ ├── scrap/ │ └── virtual_display/ ├── res/ (136 items) │ ├── DEBIAN/ │ ├── fdroid/ │ ├── msi/ │ │ ├── CustomActions/ │ │ ├── Package/ │ │ ├── Language/ │ │ ├── UI/ │ │ └── ... │ ├── pam.d/ │ ├── vcpkg/ │ │ ├── aom/ │ │ ├── ffmpeg/ │ │ ├── libvpx/ │ │ ├── libyuv/ │ │ ├── mfx-dispatch/ │ │ └── opus/ │ ├── PKGBUILD │ ├── bump.sh │ ├── devices.py │ ├── gen_icon.sh │ ├── icon.ico │ └── ... ├── src/ (174 items) │ ├── client/ │ ├── hbbs_http/ │ ├── lang/ (48 items) │ ├── platform/ │ ├── plugin/ │ ├── privacy_mode/ │ ├── server/ │ ├── ui/ │ ├── ... ├── .gitattributes ├── .gitignore ├── Cargo.lock ├── Cargo.toml ├── Dockerfile ├── LICENCE ├── README.md ├── build.py ├── build.rs ├── entrypoint.sh ├── terminal.md └── vcpkg.json ``` --- ## 3. Technical Implementation Details ### Core Modules - **Networking & Connection:** - `src/client.rs`: Client connection initiation, media stream management. - `src/rendezvous_mediator.rs`: NAT traversal, relay server communication. - `src/port_forward.rs`: Port forwarding and relay management. - `src/server.rs`: Server-side connection and media management. - **Media Processing:** - `libs/scrap/`: Screen capture and video encoding/decoding (DXGI, Quartz, X11, Wayland). - `libs/enigo/`: Cross-platform input simulation (keyboard/mouse). - `libs/clipboard/`: Clipboard synchronization and file transfer. - `libs/virtual_display/`: Virtual display driver interface and management. - **UI Layer:** - `flutter/lib/`: Flutter UI code for desktop, mobile, and web. - `src/ui.rs`, `src/ui_interface.rs`: UI event handling and session management. - `flutter/windows/runner/`: Windows native Flutter host and window management. - **Localization:** - `src/lang/`: Static language resource modules using `lazy_static` for translations. - Each language file exports a static `HashMap` of key-value pairs for UI strings. - **Plugin System:** - `src/plugin/`: Plugin loading, configuration, IPC, native handlers. - Dynamic loading via `dlopen`-style libraries. - Callback-based communication and event dispatch. - **Privacy & Security:** - `src/privacy_mode.rs`: Privacy mode implementations with Windows-specific strategies. - `src/updater.rs`: Auto-update and manual update management. - `src/virtual_display_manager.rs`: Virtual display driver installation and management. --- ### Build & Deployment - **Build Scripts:** - `build.rs`: Rust build script for platform-specific compilation and resource embedding. - `build.py`: Python orchestrator for multi-platform builds and packaging. - `.github/workflows/`: CI/CD pipelines for macOS, Windows, Linux, Android, Flutter builds, signing, and publishing. - **Packaging:** - `res/msi/`: Windows installer custom actions and resources. - `res/vcpkg/`: Package definitions for dependencies like FFmpeg, libyuv. - `libs/portable/`: Portable packaging utilities and embedded resource management. --- ## 4. Development Patterns and Standards - **Code Organization:** - Modular directory structure separating platform-specific code (`src/platform/`), UI (`flutter/lib/`), core logic (`src/`), and libraries (`libs/`). - Use of Rust traits and interfaces for abstraction (`TraitCapturer`, `PrivacyMode`, `Interface`). - Separation of UI and business logic, with Flutter UI components decoupled from core Rust logic. - **Testing & CI:** - Extensive GitHub Actions workflows for cross-platform build and test automation. - Use of example programs (`libs/enigo/examples/`, `libs/scrap/examples/`) for manual and automated testing. - **Error Handling:** - Consistent use of `ResultType` and macros (`bail!`, `allow_err!`) for error propagation. - Logging via `log` crate for diagnostics. - **Configuration Management:** - Environment variables (`VCPKG_ROOT`, `PUID`, `PGID`) for build and runtime configuration. - Use of TOML and JSON for configuration files and metadata. - **Localization:** - Static resource bundles per language using `lazy_static` and `HashMap`. - Consistent key naming across languages for easy lookup and maintenance. - **Plugin Development:** - Dynamic loading with symbol resolution. - Callback-based event handling. - Configuration and metadata management via JSON and protocol buffers. --- ## 5. Integration and Dependencies - **External Libraries:** - Rust crates: `tokio` (async runtime), `serde` (serialization), `reqwest` (HTTP client), `protobuf` (message serialization), `log` (logging). - System libraries: Windows API (`winapi`), macOS frameworks (`core_graphics`, `objc`), Linux X11/Wayland libraries. - Flutter SDK and plugins for UI. - Multimedia codecs: `libvpx`, `aom`, `libyuv`, `opus`. - Clipboard and input libraries: `arboard`, `clipboard_master`, `enigo`. - **Internal Dependencies:** - `hbb_common`: Shared utilities, message definitions, network wrappers. - `libs/clipboard`, `libs/enigo`, `libs/scrap`: Platform-specific system integration. - `src/plugin`: Plugin management and native handlers. - `flutter/lib`: UI and platform integration. - **API Dependencies:** - Communication with `rustdesk-server` for signaling and relay. - D-Bus interfaces for Wayland portals. - Windows Print Spooler APIs for printer management. - System tray and native window management APIs. --- ## 6. Usage and Operational Guidance ### Building the Project - Use `build.py` at the root for orchestrated multi-platform builds. - Platform-specific build scripts and CI workflows automate building for Windows, macOS, Linux, Android, and iOS. - Dependencies managed via `vcpkg` and Rust's Cargo. - Flutter UI builds integrated via GitHub Actions and local scripts. ### Running the Application - The main executable is built from `src/main.rs` and related modules. - Flutter UI runs as a separate process or embedded window (`flutter/windows/runner`). - Plugins are dynamically loaded at runtime from configured directories. - Configuration files and environment variables control runtime behavior. ### Localization - Language resources are static Rust modules under `src/lang/`. - The application selects language modules based on user preference or system locale. - UI components query the static `T` maps for localized strings. ### Extending the System - Add new plugins by placing shared libraries in the plugin directory and updating plugin metadata. - Extend localization by adding new language files under `src/lang/` following existing patterns. - Add platform-specific features by extending `src/platform/` modules. - Use provided examples in `libs/enigo/examples/` and `libs/scrap/examples/` for testing input and capture functionalities. ### Debugging and Logging - Logging is enabled via the `log` crate; configure log levels via environment variables. - Use CI workflows and example programs to validate builds and runtime behavior. - Clipboard, input, and media capture modules provide detailed logs for troubleshooting. --- # Summary This project is a mature, modular, and cross-platform remote desktop and collaboration system built with Rust and Flutter. It features a layered architecture separating core logic, platform-specific code, UI, and plugins. The extensive localization support, plugin system, and platform abstractions enable scalability and extensibility. Comprehensive build and deployment automation ensures multi-platform support. The repository structure and code organization facilitate maintainability and rapid development. --- # Actionable Insights for Developers and AI Agents - **To understand core logic:** Start with `src/client.rs`, `src/server.rs`, and `src/rendezvous_mediator.rs` for connection and media management. - **For UI development:** Explore `flutter/lib/` for Flutter UI components and `flutter/windows/runner` for Windows native embedding. - **For platform-specific features:** Check `src/platform/`, `libs/enigo/`, `libs/clipboard/`, and `libs/scrap/`. - **To add localization:** Add new language files under `src/lang/` following the existing `lazy_static` pattern. - **To develop plugins:** Use `src/plugin/` modules as reference for plugin lifecycle and IPC communication. - **For build and deployment:** Use `build.py` and `.github/workflows/` for automated builds; consult `res/msi/` and `res/vcpkg/` for packaging. - **For debugging:** Enable logging via environment variables; use example programs in `libs/enigo/examples/` and `libs/scrap/examples/`. --- # End of DETAILS.md