# thedusk4203/dblocker architecture

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

- Interactive diagram: https://gitdiagram.com/thedusk4203/dblocker
- Repository: https://github.com/thedusk4203/dblocker

## Overview

DBlocker is a user-controlled browser extension that protects selected sites from popup/redirect traps, click overlays, and unwanted embedded frames. The main workflow is: the user enables protection for a site, the page controller checks policy with the background context, and the page engine blocks detected behavior; the popup lets users review events and manage persistent allow rules. Chromium and Firefox have parallel implementations. The excerpts show controller messaging, policy checks, and parts of the page engine; some background dispatch details and other capabilities are documented or implied by message names but not fully sampled, so uncertain wiring is omitted.

Main entry points: [`chromium/background.js`](https://github.com/thedusk4203/dblocker/blob/main/chromium/background.js) (Chromium background), [`firefox/background.js`](https://github.com/thedusk4203/dblocker/blob/main/firefox/background.js) (Firefox background), [`chromium/src/controller.js`](https://github.com/thedusk4203/dblocker/blob/main/chromium/src/controller.js) (Chromium controller), [`firefox/src/controller.js`](https://github.com/thedusk4203/dblocker/blob/main/firefox/src/controller.js) (Firefox controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_controls["User controls"]
  node_chromium_popup["Chromium popup<br/>[popup.js]"]
  node_firefox_popup["Firefox popup<br/>[popup.js]"]
  node_chromium_options["Chromium settings<br/>[options.js]"]
  node_firefox_options["Firefox settings<br/>[options.js]"]
end

subgraph group_page["Page protection"]
  node_chromium_controller["Chromium controller<br/>[controller.js]"]
  node_firefox_controller["Firefox controller<br/>[controller.js]"]
  node_chromium_engine["Chromium page engine<br/>[page-engine.js]"]
  node_firefox_engine["Firefox page engine<br/>[page-engine.js]"]
end

subgraph group_runtime["Extension runtime"]
  node_chromium_background["Chromium background<br/>[background.js]"]
  node_firefox_background["Firefox background<br/>[background.js]"]
end

subgraph group_state["Policy and state"]
  node_chromium_shared["Chromium shared rules<br/>[shared.js]"]
  node_firefox_shared["Firefox shared rules<br/>[shared.js]"]
  node_chromium_psl["Chromium site matching<br/>[psl.js]"]
  node_firefox_psl["Firefox site matching<br/>[psl.js]"]
  node_chromium_storage[("Chromium extension storage")]
  node_firefox_storage[("Firefox extension storage")]
end

node_user(("User"))
node_site(("Protected website"))
node_browser_api["Browser APIs"]

node_user -->|"manages protection"| node_chromium_popup
node_user -->|"manages protection"| node_firefox_popup
node_user -->|"configures settings"| node_chromium_options
node_user -->|"configures settings"| node_firefox_options
node_site -->|"loads page"| node_chromium_controller
node_site -->|"loads page"| node_firefox_controller
node_chromium_controller -->|"requests policy"| node_chromium_background
node_firefox_controller -->|"requests policy"| node_firefox_background
node_chromium_controller -->|"sends telemetry"| node_chromium_background
node_firefox_controller -->|"sends telemetry"| node_firefox_background
node_chromium_background -.->|"returns preparation"| node_chromium_controller
node_firefox_background -.->|"returns preparation"| node_firefox_controller
node_chromium_background -->|"matches site keys"| node_chromium_psl
node_firefox_background -->|"matches site keys"| node_firefox_psl
node_chromium_background -->|"uses policy rules"| node_chromium_shared
node_firefox_background -->|"uses policy rules"| node_firefox_shared
node_chromium_background -->|"reads and writes"| node_chromium_storage
node_firefox_background -->|"reads and writes"| node_firefox_storage
node_chromium_popup -->|"loads and updates config"| node_chromium_shared
node_firefox_popup -->|"loads and updates config"| node_firefox_shared
node_chromium_options -->|"loads and updates config"| node_chromium_shared
node_firefox_options -->|"loads and updates config"| node_firefox_shared
node_chromium_popup -->|"queries tabs"| node_browser_api
node_firefox_popup -->|"queries tabs"| node_browser_api
node_chromium_options -->|"uses extension API"| node_browser_api
node_firefox_options -->|"uses extension API"| node_browser_api
node_chromium_controller -->|"sends messages"| node_browser_api
node_firefox_controller -->|"sends messages"| node_browser_api
node_chromium_background -->|"handles browser events"| node_browser_api
node_firefox_background -->|"handles browser events"| node_browser_api
node_chromium_engine -->|"blocks page traps"| node_site
node_firefox_engine -->|"blocks page traps"| node_site

click node_chromium_popup "https://github.com/thedusk4203/dblocker/blob/main/chromium/popup/popup.js"
click node_firefox_popup "https://github.com/thedusk4203/dblocker/blob/main/firefox/popup/popup.js"
click node_chromium_options "https://github.com/thedusk4203/dblocker/blob/main/chromium/options/options.js"
click node_firefox_options "https://github.com/thedusk4203/dblocker/blob/main/firefox/options/options.js"
click node_chromium_controller "https://github.com/thedusk4203/dblocker/blob/main/chromium/src/controller.js"
click node_firefox_controller "https://github.com/thedusk4203/dblocker/blob/main/firefox/src/controller.js"
click node_chromium_engine "https://github.com/thedusk4203/dblocker/blob/main/chromium/src/page-engine.js"
click node_firefox_engine "https://github.com/thedusk4203/dblocker/blob/main/firefox/src/page-engine.js"
click node_chromium_background "https://github.com/thedusk4203/dblocker/blob/main/chromium/background.js"
click node_firefox_background "https://github.com/thedusk4203/dblocker/blob/main/firefox/background.js"
click node_chromium_shared "https://github.com/thedusk4203/dblocker/blob/main/chromium/src/shared.js"
click node_firefox_shared "https://github.com/thedusk4203/dblocker/blob/main/firefox/src/shared.js"
click node_chromium_psl "https://github.com/thedusk4203/dblocker/blob/main/chromium/src/psl.js"
click node_firefox_psl "https://github.com/thedusk4203/dblocker/blob/main/firefox/src/psl.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_chromium_popup,node_firefox_popup,node_chromium_options,node_firefox_options,node_user,node_browser_api toneBlue
class node_chromium_controller,node_firefox_controller,node_chromium_engine,node_firefox_engine toneAmber
class node_chromium_background,node_firefox_background toneMint
class node_chromium_shared,node_firefox_shared,node_chromium_psl,node_firefox_psl,node_chromium_storage,node_firefox_storage toneRose
class node_site toneIndigo
```

## Components

### User controls

- [Chromium popup](https://github.com/thedusk4203/dblocker/blob/main/chromium/popup/popup.js): `chromium/popup/popup.js`
- [Firefox popup](https://github.com/thedusk4203/dblocker/blob/main/firefox/popup/popup.js): `firefox/popup/popup.js`
- [Chromium settings](https://github.com/thedusk4203/dblocker/blob/main/chromium/options/options.js): `chromium/options/options.js`
- [Firefox settings](https://github.com/thedusk4203/dblocker/blob/main/firefox/options/options.js): `firefox/options/options.js`

### Page protection

- [Chromium controller](https://github.com/thedusk4203/dblocker/blob/main/chromium/src/controller.js): `chromium/src/controller.js`
- [Firefox controller](https://github.com/thedusk4203/dblocker/blob/main/firefox/src/controller.js): `firefox/src/controller.js`
- [Chromium page engine](https://github.com/thedusk4203/dblocker/blob/main/chromium/src/page-engine.js): `chromium/src/page-engine.js`
- [Firefox page engine](https://github.com/thedusk4203/dblocker/blob/main/firefox/src/page-engine.js): `firefox/src/page-engine.js`

### Extension runtime

- [Chromium background](https://github.com/thedusk4203/dblocker/blob/main/chromium/background.js): `chromium/background.js`
- [Firefox background](https://github.com/thedusk4203/dblocker/blob/main/firefox/background.js): `firefox/background.js`

### Policy and state

- [Chromium shared rules](https://github.com/thedusk4203/dblocker/blob/main/chromium/src/shared.js): `chromium/src/shared.js`
- [Firefox shared rules](https://github.com/thedusk4203/dblocker/blob/main/firefox/src/shared.js): `firefox/src/shared.js`
- [Chromium site matching](https://github.com/thedusk4203/dblocker/blob/main/chromium/src/psl.js): `chromium/src/psl.js`
- [Firefox site matching](https://github.com/thedusk4203/dblocker/blob/main/firefox/src/psl.js): `firefox/src/psl.js`
- **Chromium extension storage**
- **Firefox extension storage**

### Other components

- **User**
- **Protected website**
- **Browser APIs**

## Connections

- User → Chromium popup: manages protection
- User → Firefox popup: manages protection
- User → Chromium settings: configures settings
- User → Firefox settings: configures settings
- Protected website → Chromium controller: loads page
- Protected website → Firefox controller: loads page
- Chromium controller → Chromium background: requests policy
- Firefox controller → Firefox background: requests policy
- Chromium controller → Chromium background: sends telemetry
- Firefox controller → Firefox background: sends telemetry
- Chromium background → Chromium controller: returns preparation
- Firefox background → Firefox controller: returns preparation
- Chromium background → Chromium site matching: matches site keys
- Firefox background → Firefox site matching: matches site keys
- Chromium background → Chromium shared rules: uses policy rules
- Firefox background → Firefox shared rules: uses policy rules
- Chromium background → Chromium extension storage: reads and writes
- Firefox background → Firefox extension storage: reads and writes
- Chromium popup → Chromium shared rules: loads and updates config
- Firefox popup → Firefox shared rules: loads and updates config
- Chromium settings → Chromium shared rules: loads and updates config
- Firefox settings → Firefox shared rules: loads and updates config
- Chromium popup → Browser APIs: queries tabs
- Firefox popup → Browser APIs: queries tabs
- Chromium settings → Browser APIs: uses extension API
- Firefox settings → Browser APIs: uses extension API
- Chromium controller → Browser APIs: sends messages
- Firefox controller → Browser APIs: sends messages
- Chromium background → Browser APIs: handles browser events
- Firefox background → Browser APIs: handles browser events
- Chromium page engine → Protected website: blocks page traps
- Firefox page engine → Protected website: blocks page traps