# heroic-games-launcher/heroicgameslauncher architecture

> Architecture diagram of the GitHub repository heroic-games-launcher/heroicgameslauncher, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/heroic-games-launcher/heroicgameslauncher
- Repository: https://github.com/heroic-games-launcher/heroicgameslauncher

## Overview

#### Purpose and Runtime
Heroic is a cross-platform desktop game launcher for Epic, GOG, and Amazon libraries, plus sideloaded applications. It is an Electron application: Node/Electron main process manages native capabilities and game tooling; React renders the desktop UI. Vite builds/dev-serves the renderer; electron-builder packages Linux, Windows, and macOS releases. Entry points: `src/backend/main.ts`, `src/frontend/index.tsx`, `src/preload/index.ts`, `electron.vite.config.ts`.

#### Process Boundary and IPC Contract
The renderer is intentionally separated from privileged Electron/Node APIs. The preload layer exposes a constrained API surface and relays calls/events through IPC; backend handlers perform filesystem, process, credential/store, and network operations. Shared IPC/domain types reduce cross-process drift. Paths: `src/preload/ipc.ts`, `src/preload/api/index.ts`, `src/backend/ipc.ts`, `src/common/types/ipc.ts`.

#### Desktop Lifecycle and Persistent State
The backend creates and controls the application window, tray integration, custom protocols, updates, logging, connectivity monitoring, and persisted Electron stores. Startup migrations preserve compatibility with prior stored configuration and launcher metadata. Paths: `src/backend/main.ts`, `src/backend/main_window.ts`, `src/backend/electron_store.ts`, `src/backend/migration/index.ts`.

#### Store-Manager Abstraction
Store-specific managers normalize authentication, users, libraries, game metadata, and lifecycle operations behind a central manager layer. Epic uses Legendary command wrappers; GOG uses gogdl-oriented modules; Amazon uses Nile. Sideloaded games enter the same library-oriented experience. Paths: `src/backend/storeManagers/index.ts`, `src/backend/storeManagers/legendary/commands/index.ts`, `src/backend/storeManagers/gog/library.ts`, `src/backend/storeManagers/nile/library.ts`.

#### Game Install, Launch, and Download Flow
UI library/game screens request install, import, update, move, uninstall, and launch through preload IPC. Backend store commands execute external tooling and report work through the download queue/progress events; frontend download and game views consume that state. Per-game configuration and overrides supply executable, environment, and launch settings. Paths: `src/frontend/screens/Library/index.tsx`, `src/frontend/screens/Game/GamePage/index.tsx`, `src/backend/downloadmanager/downloadqueue.ts`, `src/backend/launcher.ts`.

#### Compatibility Runtimes and Platform Integration
The backend selects/configures Wine, Proton, Crossover, umu, DXVK/DXMT, anti-cheat support, prefixes, and platform-specific process/filesystem behavior. It can download/manage Wine and Proton runtimes and integrates with Steam shortcuts. This is the boundary where game launch configuration becomes OS processes and external runner binaries. Paths: `src/backend/wine/manager/ipc_handler.ts`, `src/backend/wine/runtimes/runtimes.ts`, `src/backend/utils/compatibility_layers.ts`, `src/backend/shortcuts/nonesteamgame/steamClient.ts`.

#### Renderer Composition and State
React’s root composes screen-level workflows—login, library, game detail, downloads, settings, Wine management, console mode, and embedded store webviews—over global/context state. UI state invokes preload APIs rather than backend modules directly. Localization assets are bundled under public resources. Paths: `src/frontend/App.tsx`, `src/frontend/state/ContextProvider.tsx`, `src/frontend/screens/Settings/index.tsx`, `public/locales/en/translation.json`.

#### External Services and Delivery
External dependencies include Epic/Legendary, GOG/gogdl, Amazon/Nile, Wine/Proton release sources, Steam, SteamGridDB, compatibility/wiki sources (such as ProtonDB), and GitHub release APIs. Packaging targets native installers plus Flatpak; CI builds and releases per platform. Paths: `src/backend/wiki_game_info/wiki_game_info.ts`, `src/backend/steamgrid/ipc_handler.ts`, `electron-builder.yml`, `flatpak/prepareFlatpak.js`.

Main entry points: [`src/backend/ipc.ts`](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/ipc.ts) (IPC handlers), [`src/frontend/App.tsx`](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/frontend/App.tsx) (React app shell), [`src/backend/storeManagers/index.ts`](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/storeManagers/index.ts) (Store manager layer), [`src/backend/main.ts`](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/main.ts) (Electron main)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_renderer["Renderer UI"]
  node_app["React app shell<br/>React root<br/>[App.tsx]"]
  node_ui_state["Global UI state<br/>context state"]
  node_library_ui["Library and game views<br/>React screens<br/>[index.tsx]"]
  node_settings_ui["Settings and Wine UI<br/>React screen<br/>[index.tsx]"]
  node_locales["Localization resources<br/>translation assets<br/>[translation.json]"]
end

subgraph group_bridge["Process Bridge"]
  node_preload_api["Preload API<br/>Electron preload<br/>[index.ts]"]
  node_preload_ipc["IPC relay<br/>preload IPC<br/>[ipc.ts]"]
  node_ipc_contract["Shared IPC types<br/>shared types<br/>[ipc.ts]"]
end

subgraph group_backend["Electron Backend"]
  node_main["Electron main<br/>main process<br/>[main.ts]"]
  node_desktop_lifecycle["Window and persistent state<br/>desktop lifecycle<br/>[main_window.ts]"]
  node_backend_ipc["IPC handlers<br/>main IPC<br/>[ipc.ts]"]
  node_download_queue["Download queue<br/>work queue<br/>[downloadqueue.ts]"]
  node_launcher["Game launcher<br/>launch orchestration<br/>[launcher.ts]"]
  node_compatibility["Compatibility runtimes<br/>Wine/Proton integration<br/>[runtimes.ts]"]
end

subgraph group_stores["Store Integrations"]
  node_store_managers["Store manager layer<br/>store abstraction<br/>[index.ts]"]
  node_epic_legendary["Epic via Legendary<br/>external CLI integration<br/>[index.ts]"]
  node_gog_amazon["GOG and Amazon libraries<br/>store integrations<br/>[library.ts]"]
end

subgraph group_delivery["Packaging"]
  node_package["Native and Flatpak packages<br/>release packaging"]
end

node_vite{{"Vite / Electron build<br/>build config"}}

node_vite -->|"builds renderer"| node_app
node_vite -->|"builds main process"| node_main
node_app -->|"uses"| node_ui_state
node_app -->|"composes"| node_library_ui
node_app -->|"composes"| node_settings_ui
node_app -->|"loads"| node_locales
node_library_ui -->|"requests game actions"| node_preload_api
node_settings_ui -->|"configures runtimes"| node_preload_api
node_preload_api -->|"relays through"| node_preload_ipc
node_preload_ipc -->|"IPC calls and events"| node_backend_ipc
node_ipc_contract -.->|"defines contract"| node_preload_ipc
node_ipc_contract -.->|"defines contract"| node_backend_ipc
node_main -->|"controls"| node_desktop_lifecycle
node_main -->|"registers"| node_backend_ipc
node_backend_ipc -->|"library operations"| node_store_managers
node_backend_ipc -->|"queues install and update"| node_download_queue
node_backend_ipc -->|"launches games"| node_launcher
node_backend_ipc -->|"manages runners"| node_compatibility
node_store_managers -->|"Epic operations"| node_epic_legendary
node_store_managers -->|"GOG and Amazon operations"| node_gog_amazon
node_download_queue -->|"executes store work"| node_store_managers
node_launcher -->|"uses selected runtime"| node_compatibility
node_package -->|"packages build outputs"| node_vite

click node_vite "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/electron.vite.config.ts"
click node_app "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/frontend/App.tsx"
click node_ui_state "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/frontend/state/ContextProvider.tsx"
click node_library_ui "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/frontend/screens/Library/index.tsx"
click node_settings_ui "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/frontend/screens/Settings/index.tsx"
click node_locales "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/public/locales/en/translation.json"
click node_preload_api "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/preload/api/index.ts"
click node_preload_ipc "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/preload/ipc.ts"
click node_ipc_contract "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/common/types/ipc.ts"
click node_main "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/main.ts"
click node_desktop_lifecycle "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/main_window.ts"
click node_backend_ipc "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/ipc.ts"
click node_store_managers "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/storeManagers/index.ts"
click node_epic_legendary "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/storeManagers/legendary/commands/index.ts"
click node_gog_amazon "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/storeManagers/gog/library.ts"
click node_download_queue "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/downloadmanager/downloadqueue.ts"
click node_launcher "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/launcher.ts"
click node_compatibility "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/wine/runtimes/runtimes.ts"
click node_package "https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/electron-builder.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_ui_state,node_library_ui,node_settings_ui,node_locales toneBlue
class node_preload_api,node_preload_ipc,node_ipc_contract toneAmber
class node_main,node_desktop_lifecycle,node_backend_ipc,node_download_queue,node_launcher,node_compatibility toneMint
class node_store_managers,node_epic_legendary,node_gog_amazon toneRose
class node_package toneIndigo
class node_vite toneNeutral
```

## Components

### Renderer UI

React desktop interface and UI state.

- [React app shell](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/frontend/App.tsx): React root · `src/frontend/App.tsx`
- [Global UI state](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/frontend/state/ContextProvider.tsx): context state · `src/frontend/state/ContextProvider.tsx`
- [Library and game views](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/frontend/screens/Library/index.tsx): React screens · Library workflows and game-detail actions. · `src/frontend/screens/Library/index.tsx`
- [Settings and Wine UI](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/frontend/screens/Settings/index.tsx): React screen · `src/frontend/screens/Settings/index.tsx`
- [Localization resources](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/public/locales/en/translation.json): translation assets · `public/locales/en/translation.json`

### Process Bridge

Constrained renderer-to-main API boundary.

- [Preload API](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/preload/api/index.ts): Electron preload · Exposes the renderer's constrained privileged API. · `src/preload/api/index.ts`
- [IPC relay](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/preload/ipc.ts): preload IPC · `src/preload/ipc.ts`
- [Shared IPC types](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/common/types/ipc.ts): shared types · `src/common/types/ipc.ts`

### Electron Backend

Privileged lifecycle, game, and platform services.

- [Electron main](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/main.ts): main process · Bootstraps privileged desktop services. · `src/backend/main.ts`
- [Window and persistent state](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/main_window.ts): desktop lifecycle · Window, tray, protocols, updates, stores, and migrations. · `src/backend/main_window.ts`
- [IPC handlers](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/ipc.ts): main IPC · `src/backend/ipc.ts`
- [Download queue](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/downloadmanager/downloadqueue.ts): work queue · Runs game operations and emits progress. · `src/backend/downloadmanager/downloadqueue.ts`
- [Game launcher](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/launcher.ts): launch orchestration · Applies game settings and starts games. · `src/backend/launcher.ts`
- [Compatibility runtimes](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/wine/runtimes/runtimes.ts): Wine/Proton integration · Selects runners, prefixes, compatibility layers, and Steam shortcuts. · `src/backend/wine/runtimes/runtimes.ts`

### Store Integrations

Normalized storefront and external game tooling.

- [Store manager layer](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/storeManagers/index.ts): store abstraction · Normalizes accounts, libraries, metadata, and lifecycle operations. · `src/backend/storeManagers/index.ts`
- [Epic via Legendary](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/storeManagers/legendary/commands/index.ts): external CLI integration · `src/backend/storeManagers/legendary/commands/index.ts`
- [GOG and Amazon libraries](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/src/backend/storeManagers/gog/library.ts): store integrations · gogdl- and Nile-backed library access. · `src/backend/storeManagers/gog/library.ts`

### Packaging

Native release packaging targets.

- [Native and Flatpak packages](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/electron-builder.yml): release packaging · `electron-builder.yml`

### Other components

- [Vite / Electron build](https://github.com/heroic-games-launcher/heroicgameslauncher/blob/main/electron.vite.config.ts): build config · `electron.vite.config.ts`

## Connections

- Vite / Electron build → React app shell: builds renderer
- Vite / Electron build → Electron main: builds main process
- React app shell → Global UI state: uses
- React app shell → Library and game views: composes
- React app shell → Settings and Wine UI: composes
- React app shell → Localization resources: loads
- Library and game views → Preload API: requests game actions
- Settings and Wine UI → Preload API: configures runtimes
- Preload API → IPC relay: relays through
- IPC relay → IPC handlers: IPC calls and events
- Shared IPC types → IPC relay: defines contract
- Shared IPC types → IPC handlers: defines contract
- Electron main → Window and persistent state: controls
- Electron main → IPC handlers: registers
- IPC handlers → Store manager layer: library operations
- IPC handlers → Download queue: queues install and update
- IPC handlers → Game launcher: launches games
- IPC handlers → Compatibility runtimes: manages runners
- Store manager layer → Epic via Legendary: Epic operations
- Store manager layer → GOG and Amazon libraries: GOG and Amazon operations
- Download queue → Store manager layer: executes store work
- Game launcher → Compatibility runtimes: uses selected runtime
- Native and Flatpak packages → Vite / Electron build: packages build outputs
