# bepass-org/oblivion-desktop architecture

> Architecture diagram of the GitHub repository bepass-org/oblivion-desktop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bepass-org/oblivion-desktop
- Repository: https://github.com/bepass-org/oblivion-desktop

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TD

    %% Electron Main Process
    subgraph "Electron Main Process"
        main["Main Process (src/main/main.ts)"]:::mainProcess
        menu["Menu (src/main/menu.ts)"]:::mainProcess
        ipc["IPC (src/main/ipc.ts)"]:::mainProcess
        ipcListeners["IPC Listeners (src/main/ipcListeners)"]:::mainProcess
        lib["Networking Modules (src/main/lib)"]:::mainProcess
    end

    %% Preload Scripts
    subgraph "Preload Scripts"
        preloadMain["Preload Script (src/main/preload.ts)"]:::preload
        preloadRenderer["Preload Declarations (src/renderer/preload.d.ts)"]:::preload
    end

    %% Electron Renderer Process
    subgraph "Electron Renderer Process"
        renderer["Renderer Process (React UI) (src/renderer)"]:::renderer
    end

    %% Localization & Multi-language Support
    subgraph "Localization & Multi-language Support"
        localization["Localization Files (src/localization)"]:::localization
    end

    %% Build and Configuration Tools
    subgraph "Build & Configuration Tools"
        erbConfigs["Webpack & Configs (.erb/configs)"]:::build
        erbScripts["Build/Post-Install Scripts (.erb/scripts)"]:::build
        scripts["Additional Build Scripts (script)"]:::build
    end

    %% External Integrations
    subgraph "External Integrations"
        external["Cloudflare Warp & SingBox Integration"]:::external
    end

    %% Relationships
    %% IPC communication between Renderer and Main Process
    renderer -->|"IPC-request"| ipc
    ipc -->|"IPC-response"| renderer

    %% Main Process internal communication
    main -->|"manages"| menu
    main -->|"initializes"| ipc
    main -->|"triggers"| lib
    ipc -->|"delegates to"| ipcListeners

    %% Preload acts as a secure bridge
    preloadMain ---|"exposes APIs"| renderer
    preloadMain ---|"communicates with"| main
    preloadRenderer ---|"type definitions for"| renderer

    %% Localization is used by Renderer
    renderer -->|"loads"| localization

    %% Build Tools supply bundling to both Main and Renderer
    erbConfigs ---|"bundles"| main
    erbConfigs ---|"bundles"| renderer
    erbScripts ---|"runs build tasks for"| main
    erbScripts ---|"runs build tasks for"| renderer
    scripts ---|"executes scripts for"| main
    scripts ---|"executes scripts for"| renderer

    %% External dependencies used in Networking Modules
    lib ---|"integrates"| external

    %% Class Definitions
    classDef mainProcess fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef renderer fill:#aed6f1,stroke:#2874a6,stroke-width:2px;
    classDef preload fill:#abebc6,stroke:#1e8449,stroke-width:2px;
    classDef build fill:#f9e79f,stroke:#af601a,stroke-width:2px;
    classDef external fill:#fadbd8,stroke:#cb4335,stroke-width:2px;
    classDef localization fill:#d2b4de,stroke:#7d3c98,stroke-width:2px;

    %% Click Events
    click main "https://github.com/bepass-org/oblivion-desktop/blob/main/src/main/main.ts"
    click menu "https://github.com/bepass-org/oblivion-desktop/blob/main/src/main/menu.ts"
    click ipc "https://github.com/bepass-org/oblivion-desktop/blob/main/src/main/ipc.ts"
    click ipcListeners "https://github.com/bepass-org/oblivion-desktop/tree/main/src/main/ipcListeners/"
    click lib "https://github.com/bepass-org/oblivion-desktop/tree/main/src/main/lib/"
    click renderer "https://github.com/bepass-org/oblivion-desktop/tree/main/src/renderer/"
    click preloadMain "https://github.com/bepass-org/oblivion-desktop/blob/main/src/main/preload.ts"
    click preloadRenderer "https://github.com/bepass-org/oblivion-desktop/blob/main/src/renderer/preload.d.ts"
    click localization "https://github.com/bepass-org/oblivion-desktop/tree/main/src/localization/"
    click erbConfigs "https://github.com/bepass-org/oblivion-desktop/tree/main/.erb/configs/"
    click erbScripts "https://github.com/bepass-org/oblivion-desktop/tree/main/.erb/scripts/"
    click scripts "https://github.com/bepass-org/oblivion-desktop/tree/main/script/"
```
