# multiboxlabs/flow-browser architecture

> Architecture diagram of the GitHub repository multiboxlabs/flow-browser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/multiboxlabs/flow-browser
- Repository: https://github.com/multiboxlabs/flow-browser

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Pipeline
    subgraph "Build Pipeline"
        VITE["Vite Build"]:::external
        EB["electron-builder"]:::external
    end
    click VITE "https://github.com/multiboxlabs/flow-browser/blob/main/electron.vite.config.ts"
    click EB "https://github.com/multiboxlabs/flow-browser/blob/main/electron-builder.json"

    %% Renderer Process
    subgraph "Renderer Process" 
        direction TB
        R_HTML["index.html"]:::process
        R_MAIN["main.tsx"]:::process
        UI_LIB["UI Primitives"]:::modules
        BROWSER_UI["Browser Sidebar & Omnibox"]:::modules
        PROVIDERS["Context Providers"]:::modules
        ROUTES["Application Routes & Pages"]:::modules
        PDF["PDF Viewer"]:::modules
        R_ANALYTICS["Analytics (umami)"]:::modules
    end
    click R_HTML "https://github.com/multiboxlabs/flow-browser/blob/main/src/renderer/index.html"
    click R_MAIN "https://github.com/multiboxlabs/flow-browser/blob/main/src/renderer/src/main.tsx"
    click UI_LIB "https://github.com/multiboxlabs/flow-browser/tree/main/src/renderer/src/components/ui"
    click BROWSER_UI "https://github.com/multiboxlabs/flow-browser/tree/main/src/renderer/src/components/browser-ui/sidebar"
    click BROWSER_UI "https://github.com/multiboxlabs/flow-browser/tree/main/src/renderer/src/components/omnibox"
    click PROVIDERS "https://github.com/multiboxlabs/flow-browser/tree/main/src/renderer/src/components/providers"
    click ROUTES "https://github.com/multiboxlabs/flow-browser/tree/main/src/renderer/src/routes"
    click PDF "https://github.com/multiboxlabs/flow-browser/tree/main/src/renderer/src/routes/pdf-viewer/pdf-viewer"
    click R_ANALYTICS "https://github.com/multiboxlabs/flow-browser/blob/main/src/renderer/src/components/analytics/umami.tsx"

    %% Preload Bridge
    PRELOAD["Preload Bridge Script"]:::process
    click PRELOAD "https://github.com/multiboxlabs/flow-browser/blob/main/src/preload/index.ts"

    %% Main Process
    subgraph "Main Process"
        direction TB
        WM["Window Manager"]:::modules
        BM["Browser Manager"]:::modules
        IPC["IPC Manager"]:::modules
        subgraph "Modules"
            AU["Auto-update"]:::modules
            EC["Error-capture"]:::modules
            EXT["Extensions"]:::modules
            CB["Content-blocker"]:::modules
            LOG["Logs"]:::modules
            Q["Queue"]:::modules
            BS["Basic Settings"]:::modules
            SH["PostHog Analytics"]:::modules
        end
        subgraph "Storage & OS"
            SETP["Settings Persistence"]:::storage
            DS["Datastore"]:::storage
            PROT["Protocol Handlers & OS Utils"]:::storage
        end
    end
    click WM "https://github.com/multiboxlabs/flow-browser/blob/main/src/main/browser/window-manager.ts"
    click BM "https://github.com/multiboxlabs/flow-browser/blob/main/src/main/browser/browser.ts"
    click IPC "https://github.com/multiboxlabs/flow-browser/tree/main/src/main/ipc"
    click AU "https://github.com/multiboxlabs/flow-browser/blob/main/src/main/modules/auto-update.ts"
    click EC "https://github.com/multiboxlabs/flow-browser/tree/main/src/main/modules/error-capture"
    click EXT "https://github.com/multiboxlabs/flow-browser/tree/main/src/main/modules/extensions"
    click CB "https://github.com/multiboxlabs/flow-browser/blob/main/src/main/modules/content-blocker.ts"
    click LOG "https://github.com/multiboxlabs/flow-browser/blob/main/src/main/modules/logs.ts"
    click Q "https://github.com/multiboxlabs/flow-browser/blob/main/src/main/modules/queue.ts"
    click BS "https://github.com/multiboxlabs/flow-browser/blob/main/src/main/modules/basic-settings.ts"
    click SH "https://github.com/multiboxlabs/flow-browser/blob/main/src/main/modules/posthog.ts"
    click SETP "https://github.com/multiboxlabs/flow-browser/blob/main/src/main/saving/settings.ts"
    click DS "https://github.com/multiboxlabs/flow-browser/blob/main/src/main/saving/datastore.ts"
    click PROT "https://github.com/multiboxlabs/flow-browser/tree/main/src/main/browser/utility/protocols"

    %% Shared Layer
    subgraph "Shared Layer"
        FLOW["Flow IPC Definitions"]:::external
        TYPES["Shared TypeScript Types"]:::external
    end
    click FLOW "https://github.com/multiboxlabs/flow-browser/tree/main/src/shared/flow"
    click TYPES "https://github.com/multiboxlabs/flow-browser/tree/main/src/shared/types"

    %% External Services
    subgraph "External Services"
        GH["GitHub Releases"]:::external
        CWS["Chrome Web Store"]:::external
        POSTHOG["PostHog"]:::external
    end

    %% Connections
    VITE --> R_HTML
    EB --> VITE

    R_MAIN --> UI_LIB
    UI_LIB --> BROWSER_UI
    BROWSER_UI --> PROVIDERS
    PROVIDERS --> ROUTES
    ROUTES --> PDF
    ROUTES --> R_ANALYTICS

    R_MAIN -->|"ipc.invoke"| PRELOAD
    PRELOAD -->|"ipc.handle"| IPC

    IPC --> WM
    IPC --> BM
    IPC --> AU
    IPC --> EC
    IPC --> EXT
    IPC --> CB
    IPC --> LOG
    IPC --> Q
    IPC --> BS

    AU --> DS
    EC --> DS
    EXT --> DS
    CB --> DS
    LOG --> DS
    Q --> DS
    BS --> SETP
    SETP --> DS
    PROT --> BM
    SH --> DS

    AU -->|"check updates"| GH
    EXT -->|"fetch extensions"| CWS
    R_ANALYTICS -->|"track events"| POSTHOG
    SH -->|"report metrics"| POSTHOG

    %% Shared usage
    IPC --- FLOW
    IPC --- TYPES
    PRELOAD --- FLOW
    PRELOAD --- TYPES
    R_MAIN --- FLOW
    R_MAIN --- TYPES

    %% Styles
    classDef process fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef modules fill:#FFDDA0,stroke:#333,stroke-width:1px
    classDef storage fill:#D0F0C0,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
```
