How bepass-org/oblivion-desktop works
Project Type & Purpose
• This is a cross-platform Electron desktop application (Windows/Mac/Linux) for providing secure, optimized internet access.
• It leverages Electron’s main and renderer processes to create a native-feeling user interface while exposing VPN functionality (including custom WireGuard integration in Go and SingBox-based TUN support).
• Its purpose is clearly laid out in the README as providing user-friendly secure internet access and advanced networking options, with support for multiple languages and various user features (e.g., system tray, proxy, routing rules).
File Structure
• The top-level directories include configuration files (.erb directory with various webpack configs), assets (for fonts, CSS, images), scripts (automated build and post-install scripts), and src – the core source folder.
• Within src, the division is clear:
• src/main: Contains the Electron main process code, IPC setup, process management modules, and networking helper libraries (e.g., utils, pacScript, proxy, speedTestManager, etc.).
• src/renderer: Contains the React application (with components, pages, hooks, localization files and additional libraries) that renders the UI.
• Multiple webpack configuration files exist for bundling different parts of the application (main and renderer, for both development and production). This indicates a clear separation of concerns in bundling the Electron processes.
• Supporting directories such as “assets” and “@types” outline static resources and TypeScript declarations, respectively.
• Build and packaging scripts (in both the “.erb/scripts” and “script” directories) also support tasks such as notarization, cleaning builds, linking modules, and pre-/post-installation tasks.
Key Components and their Interactions
a. Main Process:
• Located in src/main, it is responsible for launching the application window, managing native menus (e.g., in src/main/menu.ts), setting up IPC channels (via ipc.ts and ipcListeners folder), and handling system-level operations (e.g., handling network stats, proxy configuration, and processing events from networking libraries).
• Libraries within src/main/lib (like sbManager, speedTestManager, and proxy) indicate the modular design to encapsulate different networking functionalities.
b. Renderer Process:
• Located in src/renderer, it comprises the React-based UI components, pages, hooks and libraries.
• This part of the project handles user interaction, settings management, graphical display of network status and other features such as speed testing and configuration modals.
• Localization files and UI shims ensure multi-language support.
c. IPC (Inter Process Communication):
d. Preload Scripts:
• Preload scripts (referenced in src/main/preload.ts and declared in type definitions for the renderer) help safely bridge the two processes by exposing necessary APIs to the renderer without compromising security.
e. Build and Configuration Tools:
• Webpack configurations, ESLint, husky, and other scripts (in .erb and script directories) represent the development-tool chain which is integral in building, packaging, and deploying the application.
• Deployment assets such as notarization scripts (for macOS) and release directories should be depicted as auxiliary components.
f. External Dependencies & Integrations:
• Integration with Cloudflare Warp (as detailed by the README) and SingBox (network tunnel) should be denoted.
Architectural Patterns and Design Principles
• Multi-Process Architecture: Emphasize the strict separation between the Electron main process (handling backend operations, system API integration, and network management) and the renderer process (handling the UI using React).
• Modular Design: Illustrate how components from src/main/lib and src/renderer (components, pages, localizations) are split into specialized modules.
• Configuration and Build Separation: Highlight the usage of webpack and separate configuration scripts for different target environments (development vs. production) as a best practice.