IPC Architecture

IPC Architecture

All communication between the Electron main process and the React renderer goes through a typed, whitelisted bridge defined in preload.ts.

Flow

Renderer (React)
     |
     |  window.api.startProcess(profile)   <- invoke (request/response)
     v
  preload.ts  (contextBridge — security boundary)
     |
     |  ipcRenderer.invoke('process:start', profile)
     v
  main.ts  ->  processManager.ts
     |
     |  win.webContents.send('console:line', profileId, line)
     v
  preload.ts  ->  window.api.onConsoleLine(cb)
     |
     v
  Renderer (AppStore.tsx -> dispatch APPEND_LOG)

Channel Names

All IPC channel strings are defined as constants in src/main/shared/types.ts under the IPC object. No magic strings are used elsewhere in the codebase.

Constant	Channel	Direction	Description
PROFILES_GET_ALL	profiles:getAll	invoke	Fetch all profiles
PROFILES_SAVE	profiles:save	invoke	Save or update a profile
PROFILES_DELETE	profiles:delete	invoke	Delete a profile by ID
PROFILES_REORDER	profiles:reorder	invoke	Persist a new profile order
PROCESS_START	process:start	invoke	Start a JAR process
PROCESS_STOP	process:stop	invoke	Stop a process
PROCESS_SEND_INPUT	process:sendInput	invoke	Write to stdin
PROCESS_GET_STATES	process:getStates	invoke	Get running process states
PROCESS_GET_LOG	process:getLog	invoke	Get activity log entries
PROCESS_CLEAR_LOG	process:clearLog	invoke	Clear activity log
PROCESS_SCAN_ALL	process:scanAll	invoke	Scan all system processes
PROCESS_KILL_PID	process:killPid	invoke	Kill a process by PID
PROCESS_KILL_ALL_JAVA	process:killAllJava	invoke	Kill all non-protected Java processes
CONSOLE_LINE	console:line	send (push)	Stream output line to renderer
SETTINGS_GET	settings:get	invoke	Get app settings
SETTINGS_SAVE	settings:save	invoke	Save app settings
DIALOG_PICK_JAR	dialog:pickJar	invoke	Open JAR file picker
DIALOG_PICK_DIR	dialog:pickDir	invoke	Open directory picker
DIALOG_PICK_JAVA	dialog:pickJava	invoke	Open Java executable picker
WINDOW_MINIMIZE	window:minimize	send	Minimize window
WINDOW_CLOSE	window:close	send	Close / hide window

Security

• contextIsolation: true — the renderer cannot access Node.js APIs directly
• nodeIntegration: false — Node.js is not injected into the renderer
• sandbox: false — required for the preload script to use ipcRenderer
• Only explicitly listed methods are exposed via contextBridge

Adding a New Channel

1. Add a constant to the IPC object in src/main/shared/types.ts
2. Register a handler in src/main/main.ts using ipcMain.handle() or ipcMain.on()
3. Expose the call in src/main/preload.ts via contextBridge.exposeInMainWorld
4. Add the type signature to src/renderer/types/index.ts