# gorhill/ublock architecture

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

- Interactive diagram: https://gitdiagram.com/gorhill/ublock
- Repository: https://github.com/gorhill/ublock

## Overview

uBlock Origin is a browser content blocker: users configure filter lists and site-specific rules, then browser requests and page content are evaluated against those rules to block or modify them. The repository also contains a separate MV3 Lite implementation with ruleset management, filtering modes, and injected scripting. The map preserves those product branches and the dashboard, logger, and picker capabilities. Some source was not sampled; edges are limited to README statements and SOURCE INDEX references, so the unsampled runtime wiring is not inferred.

Main entry points: [`platform/mv3/extension/js/admin.js`](https://github.com/gorhill/ublock/blob/master/platform/mv3/extension/js/admin.js) (Lite administration), [`src/js/storage.js`](https://github.com/gorhill/ublock/blob/master/src/js/storage.js) (Settings and lists), [`src/js/static-net-filtering.js`](https://github.com/gorhill/ublock/blob/master/src/js/static-net-filtering.js) (Network filtering), [`src/js/background.js`](https://github.com/gorhill/ublock/blob/master/src/js/background.js) (Background coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ubo["uBlock Origin"]
  node_dashboard["Dashboard<br/>[dashboard.js]"]
  node_popup["Popup controls<br/>[popup-fenix.js]"]
  node_filterlists["Filter lists<br/>[3p-filters.js]"]
  node_dynamicrules["Site rules"]
  node_storage[("Settings and lists<br/>[storage.js]")]
  node_assets["List assets<br/>[assets.js]"]
  node_background["Background coordinator<br/>[background.js]"]
  node_logger["Request logger<br/>[logger.js]"]
  node_picker["Element picker<br/>[epicker-ui.js]"]
end

subgraph group_filtering["Filtering Runtime"]
  node_parser["Filter parser"]
  node_staticnet["Network filtering"]
  node_cosmetic["Cosmetic filtering"]
  node_redirect["Redirect resources<br/>[redirect-engine.js]"]
  node_scriptlets["Page scriptlets"]
  node_engines["Dynamic engines"]
end

subgraph group_lite["uBO Lite MV3"]
  node_liteadmin["Lite administration<br/>[admin.js]"]
  node_litemodes["Filtering modes<br/>[mode-manager.js]"]
  node_literules["Ruleset manager<br/>[ruleset-manager.js]"]
  node_litescripting["Script injection"]
  node_litefilters["Custom filter UI"]
end

subgraph group_platform["Browser Integration"]
  node_liteapi["Extension storage API<br/>[ext.js]"]
  node_webextension["WebExtension APIs<br/>[vapi-background.js]"]
end

node_user(("Browser user"))
node_browser(("Browser requests"))

node_user -->|"configures"| node_popup
node_user -->|"manages lists"| node_dashboard
node_dashboard -->|"edits lists"| node_filterlists
node_filterlists -.->|"saves selection"| node_storage
node_storage -->|"loads assets"| node_assets
node_storage -->|"compiles filters"| node_parser
node_background -->|"loads filters"| node_storage
node_background -->|"uses engines"| node_engines
node_browser -.->|"dispatches events"| node_background
node_browser -.->|"requests evaluated"| node_staticnet
node_staticnet -.->|"uses syntax"| node_parser
node_browser -.->|"site rules evaluated"| node_engines
node_engines -->|"includes firewall"| node_dynamicrules
node_cosmetic -.->|"supports page filtering"| node_scriptlets
node_staticnet -.->|"uses replacements"| node_redirect
node_user -.->|"inspects activity"| node_logger
node_user -.->|"selects elements"| node_picker
node_user -.->|"configures Lite"| node_liteadmin
node_liteadmin -->|"manages rulesets"| node_literules
node_liteadmin -->|"sets modes"| node_litemodes
node_liteadmin -->|"manages injection"| node_litescripting
node_litefilters -->|"sends changes"| node_liteapi
node_litemodes -->|"generates rules"| node_literules
node_litescripting -->|"reads rulesets"| node_literules
node_liteapi -.->|"uses storage APIs"| node_webextension

click node_dashboard "https://github.com/gorhill/ublock/blob/master/src/js/dashboard.js"
click node_popup "https://github.com/gorhill/ublock/blob/master/src/js/popup-fenix.js"
click node_filterlists "https://github.com/gorhill/ublock/blob/master/src/js/3p-filters.js"
click node_dynamicrules "https://github.com/gorhill/ublock/blob/master/src/js/dynamic-net-filtering.js"
click node_storage "https://github.com/gorhill/ublock/blob/master/src/js/storage.js"
click node_assets "https://github.com/gorhill/ublock/blob/master/src/js/assets.js"
click node_background "https://github.com/gorhill/ublock/blob/master/src/js/background.js"
click node_parser "https://github.com/gorhill/ublock/blob/master/src/js/static-filtering-parser.js"
click node_staticnet "https://github.com/gorhill/ublock/blob/master/src/js/static-net-filtering.js"
click node_cosmetic "https://github.com/gorhill/ublock/blob/master/src/js/cosmetic-filtering.js"
click node_redirect "https://github.com/gorhill/ublock/blob/master/src/js/redirect-engine.js"
click node_scriptlets "https://github.com/gorhill/ublock/blob/master/src/js/scriptlet-filtering.js"
click node_engines "https://github.com/gorhill/ublock/blob/master/src/js/filtering-engines.js"
click node_logger "https://github.com/gorhill/ublock/blob/master/src/js/logger.js"
click node_picker "https://github.com/gorhill/ublock/blob/master/src/js/epicker-ui.js"
click node_liteadmin "https://github.com/gorhill/ublock/blob/master/platform/mv3/extension/js/admin.js"
click node_litemodes "https://github.com/gorhill/ublock/blob/master/platform/mv3/extension/js/mode-manager.js"
click node_literules "https://github.com/gorhill/ublock/blob/master/platform/mv3/extension/js/ruleset-manager.js"
click node_litescripting "https://github.com/gorhill/ublock/blob/master/platform/mv3/extension/js/scripting-manager.js"
click node_litefilters "https://github.com/gorhill/ublock/blob/master/platform/mv3/extension/js/filter-manager-ui.js"
click node_liteapi "https://github.com/gorhill/ublock/blob/master/platform/mv3/extension/js/ext.js"
click node_webextension "https://github.com/gorhill/ublock/blob/master/platform/common/vapi-background.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_popup,node_filterlists,node_dynamicrules,node_storage,node_assets,node_background,node_logger,node_picker,node_user,node_browser toneBlue
class node_parser,node_staticnet,node_cosmetic,node_redirect,node_scriptlets,node_engines toneAmber
class node_liteadmin,node_litemodes,node_literules,node_litescripting,node_litefilters toneMint
class node_liteapi,node_webextension toneRose
```

## Components

### uBlock Origin

- [Dashboard](https://github.com/gorhill/ublock/blob/master/src/js/dashboard.js): `src/js/dashboard.js`
- [Popup controls](https://github.com/gorhill/ublock/blob/master/src/js/popup-fenix.js): `src/js/popup-fenix.js`
- [Filter lists](https://github.com/gorhill/ublock/blob/master/src/js/3p-filters.js): `src/js/3p-filters.js`
- [Site rules](https://github.com/gorhill/ublock/blob/master/src/js/dynamic-net-filtering.js): `src/js/dynamic-net-filtering.js`
- [Settings and lists](https://github.com/gorhill/ublock/blob/master/src/js/storage.js): `src/js/storage.js`
- [List assets](https://github.com/gorhill/ublock/blob/master/src/js/assets.js): `src/js/assets.js`
- [Background coordinator](https://github.com/gorhill/ublock/blob/master/src/js/background.js): `src/js/background.js`
- [Request logger](https://github.com/gorhill/ublock/blob/master/src/js/logger.js): `src/js/logger.js`
- [Element picker](https://github.com/gorhill/ublock/blob/master/src/js/epicker-ui.js): `src/js/epicker-ui.js`

### Filtering Runtime

- [Filter parser](https://github.com/gorhill/ublock/blob/master/src/js/static-filtering-parser.js): `src/js/static-filtering-parser.js`
- [Network filtering](https://github.com/gorhill/ublock/blob/master/src/js/static-net-filtering.js): `src/js/static-net-filtering.js`
- [Cosmetic filtering](https://github.com/gorhill/ublock/blob/master/src/js/cosmetic-filtering.js): `src/js/cosmetic-filtering.js`
- [Redirect resources](https://github.com/gorhill/ublock/blob/master/src/js/redirect-engine.js): `src/js/redirect-engine.js`
- [Page scriptlets](https://github.com/gorhill/ublock/blob/master/src/js/scriptlet-filtering.js): `src/js/scriptlet-filtering.js`
- [Dynamic engines](https://github.com/gorhill/ublock/blob/master/src/js/filtering-engines.js): `src/js/filtering-engines.js`

### uBO Lite MV3

- [Lite administration](https://github.com/gorhill/ublock/blob/master/platform/mv3/extension/js/admin.js): `platform/mv3/extension/js/admin.js`
- [Filtering modes](https://github.com/gorhill/ublock/blob/master/platform/mv3/extension/js/mode-manager.js): `platform/mv3/extension/js/mode-manager.js`
- [Ruleset manager](https://github.com/gorhill/ublock/blob/master/platform/mv3/extension/js/ruleset-manager.js): `platform/mv3/extension/js/ruleset-manager.js`
- [Script injection](https://github.com/gorhill/ublock/blob/master/platform/mv3/extension/js/scripting-manager.js): `platform/mv3/extension/js/scripting-manager.js`
- [Custom filter UI](https://github.com/gorhill/ublock/blob/master/platform/mv3/extension/js/filter-manager-ui.js): `platform/mv3/extension/js/filter-manager-ui.js`

### Browser Integration

- [Extension storage API](https://github.com/gorhill/ublock/blob/master/platform/mv3/extension/js/ext.js): `platform/mv3/extension/js/ext.js`
- [WebExtension APIs](https://github.com/gorhill/ublock/blob/master/platform/common/vapi-background.js): `platform/common/vapi-background.js`

### Other components

- **Browser user**
- **Browser requests**

## Connections

- Browser user → Popup controls: configures
- Browser user → Dashboard: manages lists
- Dashboard → Filter lists: edits lists
- Filter lists → Settings and lists: saves selection
- Settings and lists → List assets: loads assets (evidence: `src/js/storage.js`)
- Settings and lists → Filter parser: compiles filters (evidence: `src/js/storage.js`)
- Background coordinator → Settings and lists: loads filters (evidence: `src/js/background.js`)
- Background coordinator → Dynamic engines: uses engines (evidence: `src/js/filtering-engines.js`)
- Browser requests → Background coordinator: dispatches events
- Browser requests → Network filtering: requests evaluated
- Network filtering → Filter parser: uses syntax
- Browser requests → Dynamic engines: site rules evaluated
- Dynamic engines → Site rules: includes firewall (evidence: `src/js/filtering-engines.js`)
- Cosmetic filtering → Page scriptlets: supports page filtering
- Network filtering → Redirect resources: uses replacements
- Browser user → Request logger: inspects activity
- Browser user → Element picker: selects elements
- Browser user → Lite administration: configures Lite
- Lite administration → Ruleset manager: manages rulesets (evidence: `platform/mv3/extension/js/admin.js`)
- Lite administration → Filtering modes: sets modes (evidence: `platform/mv3/extension/js/admin.js`)
- Lite administration → Script injection: manages injection (evidence: `platform/mv3/extension/js/admin.js`)
- Custom filter UI → Extension storage API: sends changes (evidence: `platform/mv3/extension/js/filter-manager-ui.js`)
- Filtering modes → Ruleset manager: generates rules (evidence: `platform/mv3/extension/js/mode-manager.js`)
- Script injection → Ruleset manager: reads rulesets (evidence: `platform/mv3/extension/js/scripting-manager.js`)
- Extension storage API → WebExtension APIs: uses storage APIs
