# picatz/cube architecture

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

- Interactive diagram: https://gitdiagram.com/picatz/cube
- Repository: https://github.com/picatz/cube

## Overview

CUBE is a privacy-first Chrome URL-blocking extension. Users change blocking settings, domain rules, scoped allows, and temporary bypasses in the popup; the popup persists settings and requests a sync from the background service worker, which configures Chrome’s native declarativeNetRequest rules. The popup also presents recent match activity recorded locally by the service worker. Packaged rules and the Go rule generator are shown as a separate ruleset-authoring branch. Source excerpts do not expose every popup action or service-worker registration, so only documented or excerpt-supported relationships are drawn.

Main entry points: [`background.js`](https://github.com/picatz/cube/blob/master/background.js) (Service worker), [`tools/rulegen/main.go`](https://github.com/picatz/cube/blob/master/tools/rulegen/main.go) (ABP rule generator), [`popup.js`](https://github.com/picatz/cube/blob/master/popup.js) (Popup controls), [`rules.json`](https://github.com/picatz/cube/blob/master/rules.json) (Packaged rule shards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_user_controls["User controls"]
  node_popup["Popup controls<br/>[popup.js]"]
  node_popup_view["Popup interface<br/>[popup.html]"]
  node_activity_view["Activity view<br/>[popup.js]"]
end

subgraph group_runtime["Extension runtime"]
  node_background["Service worker<br/>[background.js]"]
  node_local_storage[("Local settings")]
  node_dnr["Chrome DNR engine"]
  node_activity["Recent activity<br/>[background.js]"]
end

subgraph group_rule_data["Rulesets"]
  node_static_rules["Packaged rule shards<br/>[rules.json]"]
  node_exceptions["Compatibility exceptions"]
  node_allowlist["Widget allowlist"]
end

subgraph group_authoring["Rule authoring"]
  node_rulegen["ABP rule generator<br/>[main.go]"]
  node_filter_sources["Filter lists"]
end

node_user(("Extension user"))

node_user -->|"opens"| node_popup_view
node_popup -->|"renders"| node_popup_view
node_popup -->|"reads and writes"| node_local_storage
node_popup -->|"requests sync"| node_background
node_background -->|"reads and writes"| node_local_storage
node_background -->|"configures rules"| node_dnr
node_static_rules -->|"loaded by"| node_dnr
node_exceptions -->|"optional rules"| node_dnr
node_allowlist -->|"optional rules"| node_dnr
node_background -->|"records matches"| node_activity
node_activity -->|"stores locally"| node_local_storage
node_activity_view -->|"reads activity"| node_local_storage
node_user -->|"views activity"| node_activity_view
node_filter_sources -->|"provides lists"| node_rulegen
node_rulegen -->|"generates shards"| node_static_rules
node_rulegen -->|"generates exceptions"| node_exceptions
node_rulegen -->|"generates allowlist"| node_allowlist

click node_popup "https://github.com/picatz/cube/blob/master/popup.js"
click node_popup_view "https://github.com/picatz/cube/blob/master/popup.html"
click node_background "https://github.com/picatz/cube/blob/master/background.js"
click node_activity "https://github.com/picatz/cube/blob/master/background.js"
click node_activity_view "https://github.com/picatz/cube/blob/master/popup.js"
click node_static_rules "https://github.com/picatz/cube/blob/master/rules.json"
click node_exceptions "https://github.com/picatz/cube/blob/master/rules.exceptions.json"
click node_allowlist "https://github.com/picatz/cube/blob/master/rules.allowlist.json"
click node_rulegen "https://github.com/picatz/cube/blob/master/tools/rulegen/main.go"

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_popup,node_popup_view,node_activity_view,node_user toneBlue
class node_background,node_local_storage,node_dnr,node_activity toneAmber
class node_static_rules,node_exceptions,node_allowlist toneMint
class node_rulegen,node_filter_sources toneRose
```

## Components

### User controls

- [Popup controls](https://github.com/picatz/cube/blob/master/popup.js): `popup.js`
- [Popup interface](https://github.com/picatz/cube/blob/master/popup.html): `popup.html`
- [Activity view](https://github.com/picatz/cube/blob/master/popup.js): `popup.js`

### Extension runtime

- [Service worker](https://github.com/picatz/cube/blob/master/background.js): `background.js`
- **Local settings**
- **Chrome DNR engine**
- [Recent activity](https://github.com/picatz/cube/blob/master/background.js): `background.js`

### Rulesets

- [Packaged rule shards](https://github.com/picatz/cube/blob/master/rules.json): `rules.json`
- [Compatibility exceptions](https://github.com/picatz/cube/blob/master/rules.exceptions.json): `rules.exceptions.json`
- [Widget allowlist](https://github.com/picatz/cube/blob/master/rules.allowlist.json): `rules.allowlist.json`

### Rule authoring

- [ABP rule generator](https://github.com/picatz/cube/blob/master/tools/rulegen/main.go): `tools/rulegen/main.go`
- **Filter lists**

### Other components

- **Extension user**

## Connections

- Extension user → Popup interface: opens (evidence: `README.md`)
- Popup controls → Popup interface: renders (evidence: `popup.js`)
- Popup controls → Local settings: reads and writes (evidence: `popup.js`)
- Popup controls → Service worker: requests sync (evidence: `popup.js`)
- Service worker → Local settings: reads and writes (evidence: `background.js`)
- Service worker → Chrome DNR engine: configures rules (evidence: `README.md`)
- Packaged rule shards → Chrome DNR engine: loaded by (evidence: `README.md`)
- Compatibility exceptions → Chrome DNR engine: optional rules (evidence: `README.md`)
- Widget allowlist → Chrome DNR engine: optional rules (evidence: `README.md`)
- Service worker → Recent activity: records matches (evidence: `background.js`)
- Recent activity → Local settings: stores locally (evidence: `background.js`)
- Activity view → Local settings: reads activity (evidence: `popup.js`)
- Extension user → Activity view: views activity (evidence: `README.md`)
- Filter lists → ABP rule generator: provides lists (evidence: `README.md`)
- ABP rule generator → Packaged rule shards: generates shards (evidence: `README.md`)
- ABP rule generator → Compatibility exceptions: generates exceptions (evidence: `README.md`)
- ABP rule generator → Widget allowlist: generates allowlist (evidence: `README.md`)