# cerebroapp/cerebro architecture

> Architecture diagram of the GitHub repository cerebroapp/cerebro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cerebroapp/cerebro
- Repository: https://github.com/cerebroapp/cerebro

## Overview

1. **Overall shape**
   - Cerebro is an **Electron desktop app** with two renderer processes plus the Electron main process.
   - The architecture is split to keep the visible UI responsive while heavier plugin work happens off the main UI path.

2. **Process boundaries**
   - **Electron main process**: `app/main.development.js` / `app/main/main.js` handles app lifecycle and window creation.
   - **Primary renderer**: `app/main/*` is the user-facing launcher UI.
   - **Background renderer**: `app/background/*` is a hidden/secondary renderer used for async work, especially plugin initialization and long-running tasks.

3. **Window and app shell**
   - `app/main/createWindow/*` manages the desktop app shell: main window creation, tray icon, auto-start, update checks, URL handling, and window toggling.
   - This is the integration point for OS-level behavior such as global hotkey activation, tray menu actions, and opening the launcher UI.

4. **UI layer**
   - The visible launcher UI is built with **React** components under `app/main/components`.
   - Key UI pieces are the search shell (`Cerebro`), results list (`ResultsList`), result rows, status bar, and platform-aware icons (`SmartIcon`).
   - Styling is CSS Modules plus global/theme CSS.

5. **Client state and actions**
   - UI state is managed with a Redux-style store in `app/main/store` and reducers in `app/main/reducers`.
   - The main slices shown here are **search** and **statusBar**, with action creators in `app/main/actions`.
   - User input flows into search state, which drives result rendering and keyboard navigation/selection.

6. **Plugin subsystem**
   - The plugin system is the core functional boundary of the app.
   - `app/plugins/core/*` contains bundled plugins and plugin-management features such as available/installed/debugging plugin discovery, formatting, readme loading, and blacklist handling.
   - Core plugins include behaviors like web search, app launch, file preview, calculator, converter, settings, version, reload, and quit.

7. **Async execution boundary**
   - Long-running plugin initialization is intentionally moved to the **background renderer**.
   - `app/lib/initPlugin.js`, `initializePlugins.js`, and `app/lib/rpc.js` support message-based communication between the main UI and the background process.
   - The readme explicitly calls out that plugin `initializeAsync` runs in the background process to avoid blocking the launcher UI.

8. **External plugins**
   - In addition to built-in plugins, Cerebro supports **third-party plugins**.
   - `app/plugins/externalPlugins.js` and the plugin loader in `app/lib/plugins/*` suggest a managed plugin discovery/install path, likely backed by npm and local plugin metadata.
   - The app exposes plugin management through the launcher itself, rather than a separate admin UI.

9. **Configuration and settings**
   - Persistent app configuration is centralized in `app/lib/config.js` and plugin settings code under `app/lib/plugins/settings/*`.
   - Theme selection is part of the settings experience, with theme definitions in `app/lib/themes.ts` and CSS themes under `app/main/css/themes`.
   - The readme notes the config file lives in the OS-specific application data directory.

10. **Platform integration**
   - The app includes OS-specific behavior for **Windows and macOS/Linux differences**, visible in `SmartIcon/getFileIcon/*` and the launcher/window control code.
   - System integration also covers tray interaction, auto-start, URL handling, and update handling.

11. **Update and release flow**
   - `app/initAutoUpdater.js` and `app/main/createWindow/checkForUpdates.js` indicate built-in update checking.
   - Release publishing is handled externally by **GitHub Actions** (`.github/workflows/*`) and **electron-builder** packaging.
   - The app is built as a distributable desktop binary rather than a hosted web deployment.

12. **Build and runtime toolchain**
   - Source is bundled with **Webpack** and transpiled with **Babel**; TypeScript is used in parts of the renderer and shared code.
   - Testing uses **Jest** with mocks for Electron APIs.
   - The repo is structured around Electron packaging constraints, not a single-page web app architecture.

13. **Key data flow for an architecture diagram**
   - User opens launcher via hotkey/tray → Electron main process shows main window → React UI receives query input → search state updates → plugin engine resolves results, with heavy work delegated to background renderer → results return through RPC/message passing → user selects a result → app triggers action such as launch, copy, open file, or plugin command.

14. **Important diagram boundaries**
   - Separate **OS/Electron shell** from **visible launcher UI**.
   - Separate **UI state/rendering** from **plugin execution and initialization**.
   - Separate **built-in core plugins** from **installable external plugins**.
   - Separate **foreground interactions** from **background async work** to reflect the app’s responsiveness strategy.

Main entry points: [`app/plugins/core/index.ts`](https://github.com/cerebroapp/cerebro/blob/master/app/plugins/core/index.ts) (Core plugins), [`app/main/createWindow.js`](https://github.com/cerebroapp/cerebro/blob/master/app/main/createWindow.js) (Window shell), [`app/main/components/ResultsList/index.js`](https://github.com/cerebroapp/cerebro/blob/master/app/main/components/ResultsList/index.js) (Results list), [`app/main/main.js`](https://github.com/cerebroapp/cerebro/blob/master/app/main/main.js) (Launcher UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_electron["Electron shell"]
  node_main_process["Main process<br/>electron-entry"]
  node_window_shell["Window shell<br/>window-manager<br/>[createWindow.js]"]
  node_tray_menu["Tray menu<br/>shell-integration<br/>[AppTray.js]"]
  node_url_handler["URL handler<br/>shell-integration<br/>[handleUrl.js]"]
  node_updater["Update checks<br/>release-integration<br/>[checkForUpdates.js]"]
  node_background_process["Background renderer<br/>async-worker<br/>[background.js]"]
  node_background_window["Background window<br/>renderer-shell<br/>[createWindow.js]"]
  node_rpc_bridge["RPC bridge<br/>ipc<br/>[rpc.js]"]
end

subgraph group_ui["Launcher UI"]
  node_launcher_ui["Launcher UI<br/>renderer-root<br/>[main.js]"]
  node_cerebro_view["Cerebro view<br/>search-shell<br/>[index.js]"]
  node_results_list["Results list<br/>results-view<br/>[index.js]"]
  node_result_row["Result row<br/>item-view<br/>[index.tsx]"]
  node_status_bar_ui["Status bar<br/>ui-panel<br/>[index.tsx]"]
  node_smart_icon["Smart icon<br/>platform-icon<br/>[index.tsx]"]
  node_store["Store<br/>[configureStore.js]"]
  node_search_state["Search state<br/>state-slice<br/>[search.js]"]
  node_status_state["Status state<br/>state-slice<br/>[statusBar.js]"]
end

subgraph group_plugins["Plugin system"]
  node_plugin_core["Core plugins<br/>plugin-bundle<br/>[index.ts]"]
  node_plugin_catalog["Plugin catalog<br/>plugin-registry<br/>[index.js]"]
  node_plugin_loader["Plugin loader<br/>plugin-loader"]
  node_plugin_settings["Plugin settings<br/>settings-store<br/>[index.js]"]
  node_external_plugins["External plugins<br/>third-party-plugins<br/>[externalPlugins.js]"]
  node_config["Config<br/>[config.js]"]
end

node_main_process -->|"creates"| node_window_shell
node_main_process -->|"starts"| node_background_process
node_window_shell -->|"owns"| node_tray_menu
node_window_shell -->|"routes"| node_url_handler
node_window_shell -->|"checks"| node_updater
node_tray_menu -->|"shows"| node_launcher_ui
node_url_handler -->|"opens"| node_launcher_ui
node_background_process -->|"hosts"| node_background_window
node_launcher_ui -->|"renders"| node_cerebro_view
node_cerebro_view -->|"uses"| node_store
node_store -->|"contains"| node_search_state
node_store -->|"contains"| node_status_state
node_search_state -->|"drives"| node_results_list
node_results_list -->|"composes"| node_result_row
node_cerebro_view -->|"includes"| node_status_bar_ui
node_results_list -->|"uses"| node_smart_icon
node_plugin_core -->|"organizes"| node_plugin_catalog
node_plugin_core -->|"loads"| node_plugin_loader
node_plugin_loader -->|"communicates"| node_rpc_bridge
node_plugin_loader -->|"delegates"| node_background_process
node_plugin_catalog -->|"includes"| node_external_plugins
node_plugin_catalog -->|"reads"| node_plugin_settings
node_plugin_settings -->|"persists"| node_config
node_config -->|"configures"| node_launcher_ui
node_plugin_core -->|"provides results"| node_results_list
node_plugin_core -->|"reports status"| node_status_bar_ui

click node_main_process "https://github.com/cerebroapp/cerebro/blob/master/app/main.development.js"
click node_window_shell "https://github.com/cerebroapp/cerebro/blob/master/app/main/createWindow.js"
click node_tray_menu "https://github.com/cerebroapp/cerebro/blob/master/app/main/createWindow/AppTray.js"
click node_url_handler "https://github.com/cerebroapp/cerebro/blob/master/app/main/createWindow/handleUrl.js"
click node_updater "https://github.com/cerebroapp/cerebro/blob/master/app/main/createWindow/checkForUpdates.js"
click node_background_process "https://github.com/cerebroapp/cerebro/blob/master/app/background/background.js"
click node_background_window "https://github.com/cerebroapp/cerebro/blob/master/app/background/createWindow.js"
click node_rpc_bridge "https://github.com/cerebroapp/cerebro/blob/master/app/lib/rpc.js"
click node_launcher_ui "https://github.com/cerebroapp/cerebro/blob/master/app/main/main.js"
click node_cerebro_view "https://github.com/cerebroapp/cerebro/blob/master/app/main/components/Cerebro/index.js"
click node_results_list "https://github.com/cerebroapp/cerebro/blob/master/app/main/components/ResultsList/index.js"
click node_result_row "https://github.com/cerebroapp/cerebro/blob/master/app/main/components/ResultsList/Row/index.tsx"
click node_status_bar_ui "https://github.com/cerebroapp/cerebro/blob/master/app/main/components/StatusBar/index.tsx"
click node_smart_icon "https://github.com/cerebroapp/cerebro/blob/master/app/main/components/SmartIcon/index.tsx"
click node_store "https://github.com/cerebroapp/cerebro/blob/master/app/main/store/configureStore.js"
click node_search_state "https://github.com/cerebroapp/cerebro/blob/master/app/main/reducers/search.js"
click node_status_state "https://github.com/cerebroapp/cerebro/blob/master/app/main/reducers/statusBar.js"
click node_plugin_core "https://github.com/cerebroapp/cerebro/blob/master/app/plugins/core/index.ts"
click node_plugin_catalog "https://github.com/cerebroapp/cerebro/blob/master/app/plugins/core/plugins/index.js"
click node_plugin_loader "https://github.com/cerebroapp/cerebro/blob/master/app/lib/initializePlugins.js"
click node_plugin_settings "https://github.com/cerebroapp/cerebro/blob/master/app/lib/plugins/settings/index.js"
click node_external_plugins "https://github.com/cerebroapp/cerebro/blob/master/app/plugins/externalPlugins.js"
click node_config "https://github.com/cerebroapp/cerebro/blob/master/app/lib/config.js"

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_main_process,node_window_shell,node_tray_menu,node_url_handler,node_updater,node_background_process,node_background_window,node_rpc_bridge toneBlue
class node_launcher_ui,node_cerebro_view,node_results_list,node_result_row,node_status_bar_ui,node_smart_icon,node_store,node_search_state,node_status_state toneAmber
class node_plugin_core,node_plugin_catalog,node_plugin_loader,node_plugin_settings,node_external_plugins,node_config toneMint
```

## Components

### Electron shell

Main and background processes that manage windows and OS integration.

- [Main process](https://github.com/cerebroapp/cerebro/blob/master/app/main.development.js): electron-entry · Application lifecycle and top-level Electron bootstrapping. · `app/main.development.js`
- [Window shell](https://github.com/cerebroapp/cerebro/blob/master/app/main/createWindow.js): window-manager · Creates and controls the launcher window, tray, updates, URL handling, and auto-start. · `app/main/createWindow.js`
- [Tray menu](https://github.com/cerebroapp/cerebro/blob/master/app/main/createWindow/AppTray.js): shell-integration · Tray icon and menu actions for showing and toggling the app. · `app/main/createWindow/AppTray.js`
- [URL handler](https://github.com/cerebroapp/cerebro/blob/master/app/main/createWindow/handleUrl.js): shell-integration · Handles external URL activation and routing into the app shell. · `app/main/createWindow/handleUrl.js`
- [Update checks](https://github.com/cerebroapp/cerebro/blob/master/app/main/createWindow/checkForUpdates.js): release-integration · Built-in update discovery and update flow hooks. · `app/main/createWindow/checkForUpdates.js`
- [Background renderer](https://github.com/cerebroapp/cerebro/blob/master/app/background/background.js): async-worker · Hidden renderer used for long-running async work and plugin initialization. · `app/background/background.js`
- [Background window](https://github.com/cerebroapp/cerebro/blob/master/app/background/createWindow.js): renderer-shell · Secondary window bootstrap for the background process. · `app/background/createWindow.js`
- [RPC bridge](https://github.com/cerebroapp/cerebro/blob/master/app/lib/rpc.js): ipc · Message-based communication between foreground and background contexts. · `app/lib/rpc.js`

### Launcher UI

Visible renderer, state, and presentation components.

- [Launcher UI](https://github.com/cerebroapp/cerebro/blob/master/app/main/main.js): renderer-root · Primary renderer entry for the visible command launcher. · `app/main/main.js`
- [Cerebro view](https://github.com/cerebroapp/cerebro/blob/master/app/main/components/Cerebro/index.js): search-shell · Main search surface and launcher composition. · `app/main/components/Cerebro/index.js`
- [Results list](https://github.com/cerebroapp/cerebro/blob/master/app/main/components/ResultsList/index.js): results-view · Renders search results and keyboard-driven selection. · `app/main/components/ResultsList/index.js`
- [Result row](https://github.com/cerebroapp/cerebro/blob/master/app/main/components/ResultsList/Row/index.tsx): item-view · Single result presentation and interaction row. · `app/main/components/ResultsList/Row/index.tsx`
- [Status bar](https://github.com/cerebroapp/cerebro/blob/master/app/main/components/StatusBar/index.tsx): ui-panel · Status and hint area shown in the launcher. · `app/main/components/StatusBar/index.tsx`
- [Smart icon](https://github.com/cerebroapp/cerebro/blob/master/app/main/components/SmartIcon/index.tsx): platform-icon · Platform-aware file and item icon resolution. · `app/main/components/SmartIcon/index.tsx`
- [Store](https://github.com/cerebroapp/cerebro/blob/master/app/main/store/configureStore.js): state-store · Redux-style store wiring for renderer state. · `app/main/store/configureStore.js`
- [Search state](https://github.com/cerebroapp/cerebro/blob/master/app/main/reducers/search.js): state-slice · Query and results state for launcher search. · `app/main/reducers/search.js`
- [Status state](https://github.com/cerebroapp/cerebro/blob/master/app/main/reducers/statusBar.js): state-slice · Status bar state and messages. · `app/main/reducers/statusBar.js`

### Plugin system

Built-in plugins, external plugins, and async plugin loading.

- [Core plugins](https://github.com/cerebroapp/cerebro/blob/master/app/plugins/core/index.ts): plugin-bundle · Bundled plugins and plugin-management capabilities. · `app/plugins/core/index.ts`
- [Plugin catalog](https://github.com/cerebroapp/cerebro/blob/master/app/plugins/core/plugins/index.js): plugin-registry · Discovers installed, available, debugging, and readme metadata for plugins. · `app/plugins/core/plugins/index.js`
- [Plugin loader](https://github.com/cerebroapp/cerebro/blob/master/app/lib/initializePlugins.js): plugin-loader · Loads and initializes plugins, including async initialization in the background. · `app/lib/initializePlugins.js`
- [Plugin settings](https://github.com/cerebroapp/cerebro/blob/master/app/lib/plugins/settings/index.js): settings-store · Validation and retrieval of persisted plugin settings. · `app/lib/plugins/settings/index.js`
- [External plugins](https://github.com/cerebroapp/cerebro/blob/master/app/plugins/externalPlugins.js): third-party-plugins · Managed third-party plugin discovery and install path. · `app/plugins/externalPlugins.js`
- [Config](https://github.com/cerebroapp/cerebro/blob/master/app/lib/config.js): app-config · Persistent application configuration and theme selection. · `app/lib/config.js`

## Connections

- Main process → Window shell: creates · Bootstraps the visible window and shell integrations.
- Main process → Background renderer: starts · Launches the hidden async renderer for background work.
- Window shell → Tray menu: owns · Builds tray actions and app visibility controls.
- Window shell → URL handler: routes · Converts OS URL activations into app behavior.
- Window shell → Update checks: checks · Triggers update discovery during app lifecycle.
- Tray menu → Launcher UI: shows · Brings the launcher UI to the foreground.
- URL handler → Launcher UI: opens · Hands external activation into the launcher renderer.
- Background renderer → Background window: hosts · Runs hidden renderer window bootstrap.
- Launcher UI → Cerebro view: renders · Mounts the main search shell.
- Cerebro view → Store: uses · Connects UI to application state.
- Store → Search state: contains · Holds query and result state.
- Store → Status state: contains · Holds status bar state.
- Search state → Results list: drives · Controls result rendering and selection.
- Results list → Result row: composes · Displays each result as an interactive row.
- Cerebro view → Status bar: includes · Shows status and helper messages.
- Results list → Smart icon: uses · Renders file and item icons with platform awareness.
- Core plugins → Plugin catalog: organizes · Groups core plugin discovery and management features.
- Core plugins → Plugin loader: loads · Coordinates plugin startup and initialization.
- Plugin loader → RPC bridge: communicates · Uses message passing to offload async work.
- Plugin loader → Background renderer: delegates · Runs initializeAsync work outside the main UI path.
- Plugin catalog → External plugins: includes · Surfaces third-party plugin sources and installs.
- Plugin catalog → Plugin settings: reads · Loads plugin configuration and validation state.
- Plugin settings → Config: persists · Stores plugin-related settings in app config.
- Config → Launcher UI: configures · Feeds theme and user preferences into the UI.
- Core plugins → Results list: provides results · Supplies search results and plugin actions to the launcher.
- Core plugins → Status bar: reports status · Feeds plugin status and contextual messages.
