Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork15.4k
Add DETAILS.md for improved documentation#12285
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Open
ginylil-tech wants to merge1 commit intorustdesk:masterChoose a base branch
base:master
Could not load branches
Branch not found:{{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline, and old review comments may become outdated.
Uh oh!
There was an error while loading.Please reload this page.
Open
Changes fromall commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Jump to
Jump to file
Failed to load files.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Diff view
Diff view
Add DETAILS.md for improved documentation
- Loading branch information
Uh oh!
There was an error while loading.Please reload this page.
commit00f659c77e65cdc3e49e0aa02deed10a9a79cb3d
There are no files selected for viewing
308 changes: 308 additions & 0 deletionsDETAILS.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,308 @@ | ||
| # 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 |
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.