How multiboxlabs/flow-browser works
Project type and purpose
• This is Flow Browser: a full-stack, desktop web browser built on Electron.
• It combines a Node.js “main” process (application logic, modules, OS integration) with a Chromium-based “renderer” process (UI built in React + Vite).
File structure
• Top-level directories:
• scripts/ – custom CLI scripts (e.g., electron-upgrader)
• src/main/ – Electron “main” process code: window & browser management, IPC channels, modules (auto-update, extensions, store, settings).
• src/preload/ – preload script exposing safe APIs to the renderer.
• src/renderer/ – React & TypeScript UI (bundled by Vite); includes public assets (offline games), components, routes, hooks.
• src/shared/ – shared TypeScript types & Flow IPC interfaces.
• electron.vite.config.ts, electron-builder.json – build & packaging configuration.
Key insights from README
• Built on Electron + Chromium.
• Supports Chrome extensions, multi-profiles, tab & space management, offline games, native ad-block, Widevine DRM.
• Uses a command palette, sidebar UI, persistent storage.
• Packaging with electron-builder, release workflows in .github/workflows.
Main components
A. Electron Shell (Node + Chromium)
B. Main Process
• Window Manager & Browser Manager
• IPC Manager (channels under src/main/ipc)
• Modules:
– auto-update, error-capture, extensions, content-blocker, logs, settings, queue, datastore (src/main/saving/datastore.ts)
• OS Integration: file system, notifications, protocol handlers
C. Preload Script
• Exposes sanitized IPC APIs and utilities to the renderer
D. Renderer Process (React UI)
• Vite-bundled UI, uses React components & hooks
• Routes & pages (src/renderer/src/routes)
• Sidebar, omnibox, settings, games, PDF viewer
• Providers & context for state (tabs, spaces, profiles, shortcuts)
E. Shared Layer
• TypeScript interfaces for IPC messages & data flows (src/shared/flow + src/shared/types)
F. External Services
• Update server (GitHub Releases, electron-upgrader scripts)
• Analytics (PostHog)
• Chrome Web Store for extensions
G. Storage
• Datastore (likely JSON/SQLite on disk)
• Extensions data, profiles, settings persisted under app data directory
Relationships & interactions
1. User interacts with UI (mouse/keyboard) → React components
2. UI calls exposed APIs in Preload → sends IPC messages to Main
3. Main Process receives IPC → invokes Modules (e.g., load settings, open tab, block content, update app)
4. Modules may read/write Datastore or call OS APIs → result returned via IPC to Renderer
5. Renderer updates UI state based on IPC response
6. Background tasks: auto-update checks → download via electron-upgrader → trigger restart
7. Extension host integration: Main injects extension scripts into BrowserWindow sessions
Architectural patterns & design principles
• Process separation: Main vs. Renderer vs. Preload
• Module-based design in Main (each concern in its own module)
• Unidirectional data flow via IPC channels (shared interfaces in src/shared/flow)
• React component hierarchy & context providers in Renderer
• Build pipeline: Vite for web assets, electron-builder for packaging
• Clear boundary between public assets (games) and bundled React code
Technologies & frameworks
• Electron (main, renderer, preload)
• Node.js, TypeScript
• React, Vite
• electron-builder, GitHub Actions workflows
• PostHog (analytics)
• Datastore (local JSON/SQLite)
• Chrome extension APIs