> ## Documentation Index
> Fetch the complete documentation index at: https://catalyst.leifiyo.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How Catalyst works

> The runtime model behind Catalyst servers, files, backups, analytics, and tunnels.

Catalyst is an Electron desktop app with a React renderer and a Node.js main process. The renderer handles the interface; the main process owns the filesystem, Java processes, backup workers, network downloads, Modrinth integration, ngrok tunnels, and update checks.

## Runtime flow

<Steps>
  <Step title="Renderer calls the preload API">
    Pages call methods exposed on `window.context`, such as `createServer`, `startServer`, `listServerFiles`, or `installModrinthProject`.
  </Step>

  <Step title="Preload forwards through IPC">
    The preload bridge maps each method to `ipcRenderer.invoke(...)` or subscribes to events such as console output, server status, backup progress, and ngrok URL changes.
  </Step>

  <Step title="Main process performs the work">
    The Electron main process validates input, touches disk, starts Java, downloads content, creates archives, or manages ngrok.
  </Step>

  <Step title="Renderer receives state updates">
    The UI refreshes server records, console lines, stats, backup progress, analytics, and tunnel URLs from IPC responses and events.
  </Step>
</Steps>

## Main data paths

Catalyst stores mutable data under Electron's `userData` directory:

```text theme={null}
userData/
  servers.json
  servers.json.bak
  servers/
    <server-id>/
      server.jar
      server.properties
      backups/
      plugins/
      mods/
      .catalyst/
  runtimes/
  ngrok/
  app_preferences.json
  ai_assistant_settings.json
```

See [Data storage](/docs/reference/data-storage) for the full layout.

## Safety boundaries

<Columns cols={2}>
  <Card title="Renderer sandbox" icon="shield">
    The window runs with `contextIsolation` and `sandbox` enabled. The renderer does not get raw Node.js access.
  </Card>

  <Card title="Safe file paths" icon="folder-lock">
    File operations resolve paths inside a server root and reject traversal, absolute paths, and unsafe names.
  </Card>

  <Card title="Zip import checks" icon="archive-restore">
    Imported archives need a manifest, are size limited, and are protected against zip-slip paths.
  </Card>

  <Card title="Confirmed AI actions" icon="message-square-warning">
    The AI assistant can propose changes, but server commands and file/property writes require confirmation.
  </Card>
</Columns>