System Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• main.js
• renderer.js
• package.json
• setup.js
• index.html
• README.md
• CHANGELOG_v1.2.3.md

GeekEZ Browser is an anti-detect browser built using Electron and Puppeteer. Its architecture is designed to provide strict isolation between browser profiles, encompassing network environments, browser fingerprints, and local storage. The system leverages a multi-process model where a central Electron Main process orchestrates various components, including a web-based UI (Renderer), a dedicated proxy engine (Xray-core), and sandboxed Chromium browser instances managed by Puppeteer.

The core design philosophy is "Native Consistency," aiming to create browser environments that are indistinguishable from standard Chrome installations to bypass advanced detection systems. This is achieved by using a real Chrome browser, injecting fingerprint modifications via a dynamically generated extension, and routing all network traffic through a dedicated, per-profile proxy process.

Core Components

The application is composed of several key components that work together to provide isolated browsing environments.

This diagram shows the high-level components of the GeekEZ Browser architecture. The Electron App consists of the Main and Renderer processes, which manage individual Profile Instances. Each instance includes its own Xray-core proxy and a Puppeteer-controlled Chromium browser with loaded extensions.

Sources: main.js, renderer.js, README.md

Electron Framework

The application is built on the Electron framework, which utilizes a multi-process architecture.

Main Process

The Main process, defined in main.js, serves as the application's backend and entry point. It is responsible for:

• Application Lifecycle: Managing app events like whenReady and window-all-closed.
• Window Management: Creating and managing the main BrowserWindow.
• Backend Logic: Handling all core operations such as launching profiles, managing child processes (Xray and Chromium), and interacting with the file system.
• IPC Handling: Exposing backend functionality to the Renderer process through a set of IPC (Inter-Process Communication) handlers. All file system access and process management are exclusively handled here.

Sources: main.js:7-30, 89-390

Renderer Process

The Renderer process is the application's user interface, defined in index.html and controlled by renderer.js. It is a Chromium window that renders the UI and is responsible for:

• UI Rendering and State: Managing the DOM, applying themes, and rendering the list of profiles and settings modals.
• User Interaction: Handling all user inputs, such as button clicks, form submissions, and search queries.
• Frontend Logic: Implementing UI-specific logic like filtering profiles, managing modal states, and handling internationalization (i18n).
• Communication with Main Process: All requests for data or backend actions (e.g., launching a profile, saving settings) are sent to the Main process via the electronAPI exposed through preload.js.

Sources: renderer.js, index.html

Puppeteer and Chromium

GeekEZ Browser uses Puppeteer to programmatically control dedicated Chromium instances for each profile.

• Browser Automation: Puppeteer is used to launch Chrome with a specific set of command-line arguments that configure the proxy, user data directory, window size, and other parameters for isolation.
• Dependency Management: A specific version of Chromium (129.0.6668.58) is downloaded during the initial setup by the setup.js script using @puppeteer/browsers. This ensures a consistent browser engine across all installations.
• Process Management: The Main process (main.js) tracks each launched browser instance and its associated proxy process in the activeProcesses object. When a browser window is closed, the disconnected event is caught to terminate the corresponding Xray process.

Sources: main.js:338-372, setup.js:154-173, package.json:52-53

Xray-core Proxy Engine

Network isolation is achieved using Xray-core, a powerful proxy engine.

• Per-Profile Instantiation: For each profile launched, a dedicated xray process is spawned.
• Dynamic Configuration: The Main process generates a unique config.json for each Xray instance based on the profile's proxy settings and the chain proxy configuration. This config file is saved within the profile's specific data directory.
• Traffic Routing: The Xray process listens on a free local port, and the corresponding Chromium instance is configured to use this local SOCKS5 proxy, ensuring all of the browser's network traffic is routed through Xray.

Sources: main.js:120-134, 303-306

Fingerprint Injection

To prevent browser fingerprinting, the application generates and injects a unique fingerprint for each profile.

• Fingerprint Generation: A set of fingerprint data (User-Agent, screen resolution, WebGL, etc.) is created using the generateFingerprint function when a new profile is made. Hardware details like CPU cores and memory are also randomized.
• Dynamic Extension: Instead of direct JS hooks, the system creates a temporary Chrome extension named GeekEZ Guard for each profile at launch time.
• Script Injection: This extension contains a content.js script that is injected into every webpage at document_start. This script modifies the browser's JavaScript environment to reflect the generated fingerprint. This method is considered stealthier than other injection techniques.

Sources: main.js:103-114, CHANGELOG_v1.2.3.md:20-26

Application Startup and Setup

The initial setup is handled by a postinstall script defined in package.json.

This flowchart illustrates the automated setup process triggered after npm install, which downloads and prepares the necessary Xray-core and Chromium binaries.

Sources: package.json:11, setup.js

Profile Launch Sequence

The following diagram details the sequence of events when a user launches a browser profile.

This sequence diagram shows the interaction between the UI, Main process, and child processes when a user launches a profile.

Sources: main.js:256-389, renderer.js:632-636

Data Management

Application data, including profiles and settings, is stored in JSON files within the user's application data directory.

Sources: main.js:22-26

Data Storage Location

• Base Path: app.getPath('userData')/BrowserProfiles
• Profiles: profiles.json
• Settings: settings.json
• Profile Data: Each profile has a dedicated folder named after its ID (e.g., .../BrowserProfiles/<profile_id>) containing its browser data and Xray configuration.

Data Structures

Profile Object

A profile object stored in profiles.json contains all information for a single browser environment.

Field	Type	Description
id	string (UUID)	A unique identifier for the profile.
name	string	User-defined name for the profile.
proxyStr	string	The proxy connection string (e.g., vmess://...).
tags	Array<string>	An array of user-defined tags for organization.
fingerprint	Object	An object containing the generated browser fingerprint data.
preProxyOverride	string	Controls chain proxy usage (default, on, off).
createdAt	number	Timestamp of when the profile was created.

Sources: main.js:222-229, renderer.js:620-629

Settings Object

The settings.json file stores global application settings.

Field	Type	Description
preProxies	Array<Object>	A list of proxy nodes for the chain proxy feature.
subscriptions	Array<Object>	A list of proxy subscription URLs and their settings.
mode	string	The chain proxy mode (single, balance, failover).
enablePreProxy	boolean	Global toggle for the chain proxy feature.
userExtensions	Array<string>	A list of file paths to user-added Chrome extensions.

Sources: main.js:234-235, 243-254, renderer.js:231-233

IPC Communication API

Communication between the Renderer and Main processes is handled via IPC channels defined in main.js and exposed through preload.js.

Channel	Type	Description
get-app-info	handle	Retrieves application name and version.
launch-profile	handle	The core function to launch a browser profile instance.
delete-profile	handle	Deletes a profile and moves its data directory to a trash folder.
save-profile	handle	Creates and saves a new profile with a generated fingerprint.
update-profile	handle	Updates an existing profile's data.
get-profiles	handle	Fetches the list of all profiles from profiles.json.
save-settings	handle	Saves the global settings object to settings.json.
get-settings	handle	Retrieves the global settings object.
test-proxy-latency	handle	Spawns a temporary Xray instance to test the latency of a given proxy.
check-app-update	handle	Checks GitHub for a new application release.
download-xray-update	handle	Downloads and installs a new version of the Xray-core binary.
add-user-extension	handle	Adds a path to a user-selected Chrome extension to the settings.
get-user-extensions	handle	Retrieves the list of user-added extension paths.
profile-status	send	Sent from Main to Renderer to update the running status of a profile (running or stopped).

Sources: main.js:116-255, renderer.js:421-424