Home › Docs › Architecture

Architecture

How LastBrowser is built — Electron shell, Python backend, IPC layer, data flow, and module design.

Contents

  1. High-Level Overview
  2. Electron Main Process
  3. Module System
  4. IPC Communication
  5. Data Storage
  6. Python Backend
  7. Build & Packaging
  8. Security Model

High-Level Overview

LastBrowser is a dual-process application combining an Electron shell (frontend UI, native OS integration) with a Python backend (AI agent logic, WebUI server). The two processes communicate via HTTP and a local port.

┌─────────────────────────────────────────────────────────────────┐ │ LastBrowser Electron App │ │ ┌─────────────┐ ┌─────────────┐ ┌──────────────────────────┐ │ │ │ Main Proc │ │ Renderer(s) │ │ WebContentsViews (Tabs) │ │ │ │ (Node.js) │◄─┤ (Browser) │ │ (Isolated Per-Tab) │ │ │ │ Managers │ │ Sidebar │ │ │ │ │ │ IPC Router │ │ Workspace │ │ ┌──────┐ ┌──────┐ │ │ │ │ System Tray│ │ UI │ │ │Tab 1 │ │Tab 2 │ │ │ │ └──────┬──────┘ └─────────────┘ │ └──────┘ └──────┘ │ │ │ │ └──────────────────────────┘ │ │ │ HTTP (localhost:7889) │ │ ▼ │ │ ┌──────────────────────────────────────────────────────────────┤ │ │ Python Backend (server.py) │ │ │ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────────────────┐ │ │ │ │Hermes │ │ API │ │ Static │ │ WebSocket │ │ │ │ │Agent Core│ │ Handlers │ │ Files │ │ Sessions │ │ │ │ └──────────┘ └──────────┘ └────────┘ └──────────────────┘ │ │ └──────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────────┐ │ Local Storage (SQLite via sql.js in main process) │ │ Tabs, Workspaces, Agents, Settings, Kanban, Sessions, Tasks │ └──────────────────────────────────────────────────────────────────┘

Electron Main Process

The main process (native/main.js) is the application orchestrator. It manages:

  • Window Creation: Creates the BrowserWindow with hidden title bar (custom frameless), sidebar integration, and WebContentsView management.
  • Server Lifecycle: Spawns/stops the Python WebUI backend server via server-launcher.js. Handles graceful shutdown on app quit.
  • System Tray: Manages tray icon, context menu (Show, Restart Server, Quit), and minimize-to-tray behavior.
  • IPC Router: All renderer-to-main communication goes through a centralized IPC router (src/main/ipc/router.js).
  • Global Shortcuts: Registers Ctrl+K (Command Palette), Ctrl+Shift+M (Mute All), Ctrl+B (Toggle Sidebar).
  • WebViews: Manages WebContentsView instances for browser tabs with create/destroy/attach lifecycle.

Module System

The main process organizes functionality through a manager pattern. Each manager is a self-contained module:

workspaceManagerSession isolation, CRUD, reorder, export/import
tabManagerTab lifecycle, suspend, pin, close history (50)
agentManagerAgent CRUD, role system, task tracking, dashboard
kanbanManagerBoards, columns, cards, WIP limits, drag-drop
splitViewManagerMulti-panel layouts, resize, panel management
focusManagerPomodoro, distraction blocking, timer state
commandPaletteFuzzy search across all data types, quick actions
appManagerPinned web apps, multi-account, categories
settingsManagerPersistent settings, defaults, runtime updates
privacyManagerAdblock, cookie control, cache clearing
resourceSaverTab suspension, memory stats, exception list
sessionManagerSession CRUD, agent assignments
taskManagerTask management, status tracking
workerManagerBackground worker pool, job scheduling
cronManagerScheduled tasks, recurring jobs
pipelineManagerWorkflow pipeline, multi-step automation
notificationManagerOS notifications, badge updates
accountManagerMulti-account per app, session switching
compactManagerCompact UI mode toggle
appDefinitionManagerApp definition library (Slack, Gmail, etc.)
gitManagerGit integration, commit, diff, branch management

Each manager follows a consistent pattern:

  • Stores data via the database store abstraction
  • Exports a clean API of functions
  • Handles workspace-scoped isolation where applicable

IPC Communication

All renderer-to-main communication uses Electron's contextBridge + ipcMain.handle / ipcRenderer.invoke pattern. The IPC channel system is defined in src/shared/constants.js with ~150+ channels organized by domain:

// IPC Channel Organization (from src/shared/constants.js)
IPC.WORKSPACE_LIST, .WORKSPACE_CREATE, .WORKSPACE_DELETE...
IPC.TAB_CREATE, .TAB_CLOSE, .TAB_SUSPEND, .TAB_RESTORE...
IPC.AGENT_LIST, .AGENT_INVOKE, .AGENT_RESPONSE...
IPC.APP_LIST, .APP_CREATE, .APP_MUTE, .APP_SLEEP...
IPC.SPLIT_VIEW_CREATE, .SPLIT_VIEW_RESIZE...
IPC.FOCUS_START, .FOCUS_STOP, .FOCUS_STATUS...
IPC.KANBAN_CREATE, .KANBAN_MOVE, .KANBAN_WIP...
IPC.TAB_EXEC_JS, .TAB_SCREENSHOT, .TAB_GET_CONTENT

Security: contextIsolation: true, nodeIntegration: false. All Node.js APIs are exposed via preload.js with explicit whitelisting.

Data Storage

LastBrowser uses sql.js (SQLite compiled to WebAssembly via Emscripten) for all persistent data:

  • Collections: Tabs, workspaces, agents, settings, kanban boards/columns/cards, focus sessions, closed tabs, app accounts, worker jobs, tasks, distraction rules.
  • Database Location: Stored in the user's app data directory (electron's app.getPath('userData')).
  • Schema: Collection-based document store on top of SQLite. Each "collection" is either a table or a JSON document column.
  • Migrations: Managed by src/main/database/migrations.js for schema evolution between versions.

Python Backend

The Python backend (server.py) provides the Hermes WebUI — the AI agent interface that LastBrowser wraps:

  • Framework: Python HTTP server (FastAPI or similar) serving the WebUI on localhost:7889.
  • Server Launch: server-launcher.js spawns the Python process, waits for it to be ready, and manages its lifecycle. In dev mode, it's at the project root; in production, it's bundled as extraResources/webui/.
  • HTTP API: REST endpoints for agent interaction, session management, skill operations, etc.
  • Static Files: The WebUI frontend is served from static/ directory.

Build & Packaging

LastBrowser uses electron-builder v25 for packaging and distribution:

native/
├── package.json          # Dependencies + build scripts
├── electron-builder.config.js  # electron-builder config
├── main.js               # App entry point
├── preload.js            # Security bridge
├── server-launcher.js    # Python backend lifecycle
├── assets/               # Icons (PNG, ICO, SVG)
└── src/                  # Source modules

Windows Build:

  • Target: NSIS installer (x64) or portable .exe
  • Python backend bundled as extraResources/webui/
  • Auto-updater configured for GitHub Releases
  • GitHub Actions CI builds on windows-latest

Security Model

LastBrowser follows Electron security best practices throughout.
  • Context Isolation: Enabled. Renderer has no direct access to Node.js or Electron APIs.
  • Preload Bridge: Only explicitly whitelisted IPC channels are exposed via contextBridge.exposeInMainWorld.
  • Sandbox: Disabled (required for WebContentsView functionality), but mitigated by context isolation.
  • Session Partitions: Each workspace and app gets its own persist: session partition, preventing cross-origin data leaks.
  • Navigation Control: External links are opened in the system browser, never inside the app window.
  • Adblock: Optional built-in adblock with filter lists.
  • Cache: User-initiated cache clearing per app or global. Cookie control (block third-party).

Next: FAQ →