How cerebroapp/cerebro works
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: index.ts Core plugins · createWindow.js Window shell · index.js Results list · main.js Launcher UI
Components 23
Electron shell
Main and background processes that manage windows and OS integration.
- Main process · Application lifecycle and top-level Electron bootstrapping.
app/main.development.js - Window shell · Creates and controls the launcher window, tray, updates, URL handling, and auto-start.
app/main/createWindow.js - Tray menu · Tray icon and menu actions for showing and toggling the app.
app/main/createWindow/AppTray.js - URL handler · Handles external URL activation and routing into the app shell.
app/main/createWindow/handleUrl.js - Update checks · Built-in update discovery and update flow hooks.
app/main/createWindow/checkForUpdates.js - Background renderer · Hidden renderer used for long-running async work and plugin initialization.
app/background/background.js - Background window · Secondary window bootstrap for the background process.
app/background/createWindow.js - RPC bridge · Message-based communication between foreground and background contexts.
app/lib/rpc.js
Launcher UI
Visible renderer, state, and presentation components.
- Launcher UI · Primary renderer entry for the visible command launcher.
app/main/main.js - Cerebro view · Main search surface and launcher composition.
app/main/components/Cerebro/index.js - Results list · Renders search results and keyboard-driven selection.
app/main/components/ResultsList/index.js - Result row · Single result presentation and interaction row.
app/main/components/ResultsList/Row/index.tsx - Status bar · Status and hint area shown in the launcher.
app/main/components/StatusBar/index.tsx - Smart icon · Platform-aware file and item icon resolution.
app/main/components/SmartIcon/index.tsx - Store · Redux-style store wiring for renderer state.
app/main/store/configureStore.js - Search state · Query and results state for launcher search.
app/main/reducers/search.js - Status state · Status bar state and messages.
app/main/reducers/statusBar.js
Plugin system
Built-in plugins, external plugins, and async plugin loading.
- Core plugins · Bundled plugins and plugin-management capabilities.
app/plugins/core/index.ts - Plugin catalog · Discovers installed, available, debugging, and readme metadata for plugins.
app/plugins/core/plugins/index.js - Plugin loader · Loads and initializes plugins, including async initialization in the background.
app/lib/initializePlugins.js - Plugin settings · Validation and retrieval of persisted plugin settings.
app/lib/plugins/settings/index.js - External plugins · Managed third-party plugin discovery and install path.
app/plugins/externalPlugins.js - Config · Persistent application configuration and theme selection.
app/lib/config.js
Connections 26
- 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.