4 Electron Desktop Application

Electron Desktop Application

Relevant source files

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

• electron/disk-cache.js
• electron/main.js
• electron/preload.cjs
• src/core/cache.js
• src/core/http.js

Purpose and Scope

The Electron Desktop Application module provides the native desktop execution environment for VariantScope, packaging the web renderer inside an Electron container. This architecture allows the application to run as a standalone desktop client on macOS, Windows, and Linux, providing desktop-only features such as a native menu bar (electron/main.js:9), local HTTPS fetch proxying bypassing browser CORS restrictions (electron/main.js:124-127), native file system disk caching (electron/disk-cache.js:1-93), and secure inter-process communication (IPC) bridges (electron/preload.cjs:12-69).

This page serves as a high-level overview of the desktop application layer. For detailed technical specifications, refer to the child pages:

• For window creation, single-instance locks, and menus, see Main Process and Window Lifecycle.
• For context isolation, Content Security Policies, and the six-function IPC bridge, see Security: Allowlist, CSP and Preload Bridge.
• For HTTPS fetching rules, rate-limiting, and atomic file-backed caching, see Fetcher and Disk Cache.

graph TD
  subgraph "NaturalLanguageSpace"
    A["Electron Desktop Client"] --> B["Main Process Window Manager"]
    A --> C["Security and IPC Bridge"]
    A --> D["Disk-Backed Storage"]
  end
  subgraph "CodeEntitySpace"
    B --> E["electron/main.js"]
    C --> F["electron/preload.cjs"]
    C --> G["electron/allowlist.js"]
    C --> H["electron/csp.js"]
    D --> I["electron/disk-cache.js"]
    D --> J["electron/fetcher.js"]
  end

Loading

Sources: electron/main.js:1-12, electron/preload.cjs:1-12, electron/disk-cache.js:1-15

---

4.1 Main Process and Window Lifecycle

The Electron main process controls the application lifecycle, single-instance enforcement, and native window creation. Managed primarily via electron/main.js:1-49, the main process initializes the custom app:// protocol to serve built renderer assets securely with rigid Content Security Policies (electron/main.js:44-68). It also configures environment variables such as VARIANTSCOPE_USER_DATA for custom data paths (electron/main.js:24-25) and headless testing parameters (electron/main.js:27-31).

Additionally, native window menus and keyboard accelerators are managed through electron/main.js:9, routing application actions like file export, cache clearing, and help dialogs directly to the renderer context.

For details, see Main Process and Window Lifecycle.

Sources: electron/main.js:1-68

---

4.2 Security: Allowlist, CSP and Preload Bridge

VariantScope enforces a strict security posture for its desktop build by combining context isolation, sandboxing, and strict message validation. The preload script (electron/preload.cjs:1-12) exposes a minimal, explicit API surface (window.api) containing exactly six validated functions: fetchJson, saveFile, openExternal, listCache, deleteCache, and getAppInfo (electron/preload.cjs:12-69).

External URL navigation is restricted via an allowlist (electron/main.js:5, electron/allowlist.js), ensuring that only trusted genomic data provider domains (such as UniProt, AlphaFold, and ClinVar) can be queried or opened in the system browser (electron/main.js:91-93). Custom CSP headers are constructed dynamically via electron/main.js:6, electron/csp.js to prevent cross-site scripting vulnerabilities.

graph TD
  subgraph "Renderer Process"
    UI["Web UI Window"] -->|window.api.fetchJson| Bridge["electron/preload.cjs"]
  end
  Bridge -->|ipcRenderer.invoke| Main["electron/main.js"]
  Main -->|isTrustedSender| Security["electron/allowlist.js"]
  Main -->|fetch| External["External APIs"]

Loading

Sources: electron/main.js:5-116, electron/preload.cjs:1-69

For details, see Security: Allowlist, CSP and Preload Bridge.

---

4.3 Fetcher and Disk Cache

To ensure high performance and reliable offline operation, the desktop application routes all network requests through a dedicated background fetcher (electron/main.js:8, electron/fetcher.js) and a persistent disk cache (electron/main.js:7, electron/disk-cache.js:1-93).

The disk cache stores API responses as individual JSON files within the application's userData directory, utilizing a naming convention keyed by gene tags and SHA-256 hashes (electron/disk-cache.js:18-22). This layout enables fast traversal, size tracking per gene group (electron/disk-cache.js:54-68), and atomic writes using temporary files and renames to prevent corruption during unexpected terminations (electron/disk-cache.js:45-52).

For details, see Fetcher and Disk Cache.

Sources: electron/main.js:7-8, electron/disk-cache.js:1-93

---