# glide-browser/glide architecture

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

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

## Overview

##### Project type and purpose
- This is a desktop browser built atop Firefox’s Gecko engine.
- It injects a TypeScript-based extension layer (“Glide”) into the engine, patches C++/layout modules, bundles custom UI, offers a CLI/tooling suite, and publishes docs.

##### Top-level architectural layers/components
A. Build & Release Infrastructure
–  `.github/*`, `scripts/*`, `pnpm-workspaces`, `infra/*`
–  CI workflows → bootstrap → compile & bundle → sign → package binaries (Win/mac/Linux)
B. Configuration & Branding
–  Determines the branding overlay, platform-specific flags, installer look
C. Gecko Engine & Firefox Source
–  `src/` (layout, modules, toolkit, network, testing)
–  Standard C++ & XPCOM code, patched via `*.patch` files to add extension hooks
D. Glide Overlay & Native Bridge
–  `src/glide/cpp/Glide.h` & `moz.build` → C++ shim to register the “Glide” actor modules in the engine
–  patch files under `src/glide` merge into the Firefox build
E. Glide Extension Core (Actors & Content)
–  `src/glide/browser/actors/` → Parent/Child actors (sys.mts) for privileged messaging
–  `src/glide/browser/base/content/` → core content scripts (hinting, motions, commands, sandbox, IPC utils)
–  `src/glide/browser/components/` → UI bundles (preferences UI, tutor, customizable UI)
F. User Configuration & Runtime
–  `src/browser/app/profile/` → default user JS (betterfox.js, glide.js), pref overrides, removes
–  `src/browser/actors/` → glue code injecting Glide into a shipping Firefox build
G. Documentation & Web Site
–  `src/glide/docs/` → markdown + generated assets, code examples, API reference
–  build scripts under `scripts/` generate HTML/CSS/JS for the glide-browser.app site

##### Run-time component interactions
1. User presses a key →
2. Browser UI host (Gecko C++ UI) forwards event via extension APIs →
3. Glide content script (TS in `browser/base/content/…`) captures event, invokes hinting/motion modules →
4. If privileged work is needed (e.g. tab enumeration), send a message to a parent actor (`actors/GlideHandlerParent.sys.mjs`) →
5. Parent actor runs in a privileged context, calls C++ glue (Glide.h) → native engine APIs → returns data →
6. Content script displays hint overlays or executes nav/motion →
7. Configuration (TypeScript config files) influences behavior via dynamic module imports

–  Actors (Parent/Child sys modules)
–  Content scripts (commands, motions, hinting)
–  UI components (preferences, tutor)

##### Architectural patterns & design principles
- Extension-host pattern: privileged actors vs unprivileged content scripts
- Patch-overlay: keep core Firefox code intact, apply via moz.build & patch files
- Mono-repo with workspace tooling: scripts + pnpm to unify TS, Python, shell, C++ builds
- Clear separation of build vs runtime vs packaging vs docs

##### Technologies & frameworks
- TypeScript for extension layer
- Sys.mjs actors (Mozilla’s new JS module actor system)
- Gecko C++ engine, XPCOM
- PNPM & Node.js scripts for TS compilation, docs generation
- Shell/Python for bootstrap, packaging, signing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Release Infrastructure
    subgraph "Build & Release Infrastructure"
        direction TB
        GH[".github/"]:::build
        SCRIPTS["scripts/"]:::build
        PNPM["pnpm-workspace.yaml"]:::build
        INFRA["infra/"]:::build
    end

    %% Configuration & Branding
    subgraph "Configuration & Branding"
        direction TB
        BRAND["configs/branding/glide/"]:::config
        COMMON["configs/common/"]:::config
        LINUX["configs/linux/"]:::config
        MACOS["configs/macos/"]:::config
    end

    %% Gecko Engine & Firefox Source
    subgraph "Gecko Engine & Firefox Source"
        direction TB
        LAYOUT["src/layout/"]:::engine
        MODULES["src/modules/"]:::engine
        NETWERK["src/netwerk/"]:::engine
        TOOLKIT["src/toolkit/"]:::engine
        OTHERS["src/devtools/, src/testing/, src/build/"]:::engine
    end

    %% Glide Overlay & Native Bridge
    subgraph "Glide Overlay & Native Bridge"
        direction TB
        SHIM["C++ Shim (src/glide/cpp/)"]:::overlay
        MOZBUILD["src/glide/moz.build"]:::overlay
        PATCH["Patch Files (src/glide/)"]:::overlay
    end

    %% Glide Extension Core
    subgraph "Glide Extension Core"
        direction TB
        ACTORS["Actors\n(src/glide/browser/actors/)"]:::extension
        CONTENT["Content Scripts\n(src/glide/browser/base/content/)"]:::extension
        UI["UI Components\n(src/glide/browser/components/)"]:::extension
    end

    %% User Configuration & Runtime
    subgraph "User Configuration & Runtime"
        direction TB
        PROFILE["User Profile\n(src/browser/app/profile/)"]:::runtime
        BROWSER_ACTORS["Browser Actors\n(src/browser/actors/)"]:::runtime
    end

    %% Documentation & Web Site
    subgraph "Documentation & Website"
        direction TB
        DOCS["Docs & Site\n(src/glide/docs/)"]:::docs
        GENERATED["Generated Assets\n(src/glide/generated/)"]:::docs
    end

    %% Build-time flows
    GH -->|"CI workflows"| SCRIPTS
    SCRIPTS -->|"workspace setup"| PNPM
    PNPM -->|"dependency install"| INFRA
    INFRA -->|"bootstrap & compile"| LAYOUT
    INFRA -->|"bootstrap & compile"| MODULES
    INFRA -->|"bootstrap & compile"| NETWERK
    INFRA -->|"bootstrap & compile"| TOOLKIT
    INFRA -->|"apply branding"| BRAND
    INFRA -->|"apply branding"| COMMON
    INFRA -->|"apply branding"| LINUX
    INFRA -->|"apply branding"| MACOS
    INFRA -->|"bundle overlay"| SHIM
    INFRA -->|"bundle overlay"| PATCH
    INFRA -->|"bundle extension"| ACTORS
    INFRA -->|"bundle extension"| CONTENT
    INFRA -->|"bundle extension"| UI
    SCRIPTS -->|"generate docs"| DOCS
    DOCS -->|"use generated"| GENERATED

    %% Patch overlay into engine
    PATCH -->|"patch application"| LAYOUT
    PATCH -->|"patch application"| MODULES
    PATCH -->|"patch application"| NETWERK
    PATCH -->|"patch application"| TOOLKIT

    %% Run-time flows
    PROFILE -->|"loads configs"| CONTENT
    CONTENT -->|"IPC message"| ACTORS
    ACTORS -->|"IPC message"| CONTENT
    ACTORS -->|"native call"| SHIM
    SHIM -->|"calls APIs"| LAYOUT

    %% Documentation consumption
    DOCS -.->|"docs consumption"| PROFILE

    %% Click Events
    click GH "https://github.com/glide-browser/glide/tree/main/.github/"
    click SCRIPTS "https://github.com/glide-browser/glide/tree/main/scripts/"
    click PNPM "https://github.com/glide-browser/glide/blob/main/pnpm-workspace.yaml"
    click INFRA "https://github.com/glide-browser/glide/tree/main/infra/"
    click BRAND "https://github.com/glide-browser/glide/tree/main/configs/branding/glide/"
    click COMMON "https://github.com/glide-browser/glide/tree/main/configs/common/"
    click LINUX "https://github.com/glide-browser/glide/tree/main/configs/linux/"
    click MACOS "https://github.com/glide-browser/glide/tree/main/configs/macos/"
    click LAYOUT "https://github.com/glide-browser/glide/tree/main/src/layout/"
    click MODULES "https://github.com/glide-browser/glide/tree/main/src/modules/"
    click NETWERK "https://github.com/glide-browser/glide/tree/main/src/netwerk/"
    click TOOLKIT "https://github.com/glide-browser/glide/tree/main/src/toolkit/"
    click SHIM "https://github.com/glide-browser/glide/tree/main/src/glide/cpp/"
    click MOZBUILD "https://github.com/glide-browser/glide/blob/main/src/glide/moz.build"
    click PATCH "https://github.com/glide-browser/glide/tree/main/src/glide/"
    click ACTORS "https://github.com/glide-browser/glide/tree/main/src/glide/browser/actors/"
    click CONTENT "https://github.com/glide-browser/glide/tree/main/src/glide/browser/base/content/"
    click UI "https://github.com/glide-browser/glide/tree/main/src/glide/browser/components/"
    click PROFILE "https://github.com/glide-browser/glide/tree/main/src/browser/app/profile/"
    click BROWSER_ACTORS "https://github.com/glide-browser/glide/tree/main/src/browser/actors/"
    click DOCS "https://github.com/glide-browser/glide/tree/main/src/glide/docs/"
    click GENERATED "https://github.com/glide-browser/glide/tree/main/src/glide/generated/"

    %% Styles
    classDef build fill:#FFA500,stroke:#333,stroke-width:1px
    classDef config fill:#FFD580,stroke:#333,stroke-width:1px
    classDef engine fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef overlay fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef extension fill:#90EE90,stroke:#333,stroke-width:1px
    classDef runtime fill:#FFFACD,stroke:#333,stroke-width:1px
    classDef docs fill:#D3D3D3,stroke:#333,stroke-width:1px
```
