# efforg/privacybadger architecture

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

- Interactive diagram: https://gitdiagram.com/efforg/privacybadger
- Repository: https://github.com/efforg/privacybadger
- Video tour (about a minute): https://gitdiagram.com/efforg/privacybadger/video

## Overview

Privacy Badger is a browser extension that learns to block hidden trackers while sending GPC and Do Not Track signals. The principal flow is browser activity entering the background coordinator, where requests are evaluated and tracker decisions are persisted; content scripts and browser request handling enforce protections. Separate capabilities include click-to-activate widget replacements, social-link cleaning, and user controls. The source index supports the core coordinator and selected utilities, but several major feature implementations were not sampled; their relationships are shown only where the README documents them.

Main entry points: [`src/js/background.js`](https://github.com/efforg/privacybadger/blob/master/src/js/background.js) (Background coordinator), [`src/js/contentscripts`](https://github.com/efforg/privacybadger/tree/master/src/js/contentscripts) (Page protections), [`src/js/storage.js`](https://github.com/efforg/privacybadger/blob/master/src/js/storage.js) (Privacy state), [`src/js/webrequest.js`](https://github.com/efforg/privacybadger/blob/master/src/js/webrequest.js) (Request handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Extension runtime"]
  node_background["Background coordinator<br/>[background.js]"]
  node_webrequest["Request handling<br/>[webrequest.js]"]
  node_tabdata["Tab context<br/>[tabdata.js]"]
  node_storage[("Privacy state<br/>[storage.js]")]
  node_bootstrap["Runtime bootstrap<br/>[bootstrap.js]"]
  node_domain["Domain utilities<br/>[basedomain.js]"]
  node_suffixes["Public suffix data"]
end

subgraph group_defense["Tracker defenses"]
  node_learning["Tracker learning"]
  node_firstparties["First-party mapping"]
  node_contentscripts["Page protections"]
end

subgraph group_privacy["Privacy features"]
  node_dnt["DNT and GPC signals<br/>[dnt.js]"]
  node_fingerprinting["Fingerprint defenses<br/>[fingerprinting.js]"]
  node_storageclobber["Storage protections<br/>[clobberstorage.js]"]
  node_socialwidgets["Widget replacements"]
  node_surrogates["Surrogate dispatch<br/>[surrogates.js]"]
  node_surrogatedata["Surrogate definitions<br/>[surrogates.js]"]
  node_socialcleaning["Social link cleaning"]
end

subgraph group_interface["User controls"]
  node_popup["Toolbar controls<br/>[popup.js]"]
  node_options["Settings interface<br/>[options.js]"]
end

node_browser(("Browser activity"))
node_user(("Extension user"))

node_browser -->|"triggers"| node_background
node_background -->|"registers handling"| node_webrequest
node_background -->|"initializes state"| node_storage
node_background -->|"uses tab context"| node_tabdata
node_webrequest -->|"extracts domains"| node_domain
node_domain -->|"looks up suffixes"| node_suffixes
node_storage -->|"gets base domains"| node_domain
node_storage -->|"logs events"| node_bootstrap
node_storage -->|"subscribes script updates"| node_dnt
node_background -->|"loads"| node_learning
node_background -->|"loads"| node_socialwidgets
node_webrequest -->|"uses redirects"| node_surrogates
node_surrogates -->|"loads mappings"| node_surrogatedata
node_user -.->|"opens controls"| node_popup
node_user -.->|"configures privacy"| node_options
node_user -.->|"browses"| node_background
node_background -.->|"enforces protections"| node_contentscripts
node_contentscripts -.->|"sends signals"| node_dnt
node_learning -.->|"records decisions"| node_storage
node_webrequest -.->|"checks ownership"| node_firstparties
node_contentscripts -.->|"blocks tracking"| node_fingerprinting
node_contentscripts -.->|"protects storage"| node_storageclobber
node_socialwidgets -.->|"provides replacements"| node_surrogates
node_contentscripts -.->|"cleans links"| node_socialcleaning

click node_background "https://github.com/efforg/privacybadger/blob/master/src/js/background.js"
click node_webrequest "https://github.com/efforg/privacybadger/blob/master/src/js/webrequest.js"
click node_tabdata "https://github.com/efforg/privacybadger/blob/master/src/js/tabdata.js"
click node_storage "https://github.com/efforg/privacybadger/blob/master/src/js/storage.js"
click node_bootstrap "https://github.com/efforg/privacybadger/blob/master/src/js/bootstrap.js"
click node_domain "https://github.com/efforg/privacybadger/blob/master/src/lib/basedomain.js"
click node_suffixes "https://github.com/efforg/privacybadger/blob/master/src/lib/publicSuffixList.js"
click node_learning "https://github.com/efforg/privacybadger/blob/master/src/js/heuristicblocking.js"
click node_firstparties "https://github.com/efforg/privacybadger/blob/master/src/js/multiDomainFirstParties.js"
click node_contentscripts "https://github.com/efforg/privacybadger/tree/master/src/js/contentscripts"
click node_dnt "https://github.com/efforg/privacybadger/blob/master/src/js/contentscripts/dnt.js"
click node_fingerprinting "https://github.com/efforg/privacybadger/blob/master/src/js/contentscripts/fingerprinting.js"
click node_storageclobber "https://github.com/efforg/privacybadger/blob/master/src/js/contentscripts/clobberstorage.js"
click node_socialwidgets "https://github.com/efforg/privacybadger/blob/master/src/js/socialwidgetloader.js"
click node_surrogates "https://github.com/efforg/privacybadger/blob/master/src/js/surrogates.js"
click node_surrogatedata "https://github.com/efforg/privacybadger/blob/master/src/data/surrogates.js"
click node_socialcleaning "https://github.com/efforg/privacybadger/tree/master/src/js/firstparties"
click node_popup "https://github.com/efforg/privacybadger/blob/master/src/js/popup.js"
click node_options "https://github.com/efforg/privacybadger/blob/master/src/js/options.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_background,node_webrequest,node_tabdata,node_storage,node_bootstrap,node_domain,node_suffixes,node_browser,node_user toneBlue
class node_learning,node_firstparties,node_contentscripts toneAmber
class node_dnt,node_fingerprinting,node_storageclobber,node_socialwidgets,node_surrogates,node_surrogatedata,node_socialcleaning toneMint
class node_popup,node_options toneRose
```

## Components

### Extension runtime

- [Background coordinator](https://github.com/efforg/privacybadger/blob/master/src/js/background.js): `src/js/background.js`
- [Request handling](https://github.com/efforg/privacybadger/blob/master/src/js/webrequest.js): `src/js/webrequest.js`
- [Tab context](https://github.com/efforg/privacybadger/blob/master/src/js/tabdata.js): `src/js/tabdata.js`
- [Privacy state](https://github.com/efforg/privacybadger/blob/master/src/js/storage.js): `src/js/storage.js`
- [Runtime bootstrap](https://github.com/efforg/privacybadger/blob/master/src/js/bootstrap.js): `src/js/bootstrap.js`
- [Domain utilities](https://github.com/efforg/privacybadger/blob/master/src/lib/basedomain.js): `src/lib/basedomain.js`
- [Public suffix data](https://github.com/efforg/privacybadger/blob/master/src/lib/publicSuffixList.js): `src/lib/publicSuffixList.js`

### Tracker defenses

- [Tracker learning](https://github.com/efforg/privacybadger/blob/master/src/js/heuristicblocking.js): `src/js/heuristicblocking.js`
- [First-party mapping](https://github.com/efforg/privacybadger/blob/master/src/js/multiDomainFirstParties.js): `src/js/multiDomainFirstParties.js`
- [Page protections](https://github.com/efforg/privacybadger/tree/master/src/js/contentscripts): `src/js/contentscripts`

### Privacy features

- [DNT and GPC signals](https://github.com/efforg/privacybadger/blob/master/src/js/contentscripts/dnt.js): `src/js/contentscripts/dnt.js`
- [Fingerprint defenses](https://github.com/efforg/privacybadger/blob/master/src/js/contentscripts/fingerprinting.js): `src/js/contentscripts/fingerprinting.js`
- [Storage protections](https://github.com/efforg/privacybadger/blob/master/src/js/contentscripts/clobberstorage.js): `src/js/contentscripts/clobberstorage.js`
- [Widget replacements](https://github.com/efforg/privacybadger/blob/master/src/js/socialwidgetloader.js): `src/js/socialwidgetloader.js`
- [Surrogate dispatch](https://github.com/efforg/privacybadger/blob/master/src/js/surrogates.js): `src/js/surrogates.js`
- [Surrogate definitions](https://github.com/efforg/privacybadger/blob/master/src/data/surrogates.js): `src/data/surrogates.js`
- [Social link cleaning](https://github.com/efforg/privacybadger/tree/master/src/js/firstparties): `src/js/firstparties`

### User controls

- [Toolbar controls](https://github.com/efforg/privacybadger/blob/master/src/js/popup.js): `src/js/popup.js`
- [Settings interface](https://github.com/efforg/privacybadger/blob/master/src/js/options.js): `src/js/options.js`

### Other components

- **Browser activity**
- **Extension user**

## Connections

- Browser activity → Background coordinator: triggers (evidence: `src/js/background.js`)
- Background coordinator → Request handling: registers handling (evidence: `src/js/background.js`)
- Background coordinator → Privacy state: initializes state (evidence: `src/js/background.js`)
- Background coordinator → Tab context: uses tab context (evidence: `src/js/background.js`)
- Request handling → Domain utilities: extracts domains (evidence: `src/js/webrequest.js`)
- Domain utilities → Public suffix data: looks up suffixes (evidence: `src/lib/basedomain.js`)
- Privacy state → Domain utilities: gets base domains (evidence: `src/js/storage.js`)
- Privacy state → Runtime bootstrap: logs events (evidence: `src/js/storage.js`)
- Privacy state → DNT and GPC signals: subscribes script updates (evidence: `src/js/storage.js`)
- Background coordinator → Tracker learning: loads (evidence: `src/js/background.js`)
- Background coordinator → Widget replacements: loads (evidence: `src/js/background.js`)
- Request handling → Surrogate dispatch: uses redirects (evidence: `src/js/webrequest.js`)
- Surrogate dispatch → Surrogate definitions: loads mappings (evidence: `src/js/surrogates.js`)
- Extension user → Toolbar controls: opens controls (evidence: `README.md`)
- Extension user → Settings interface: configures privacy (evidence: `README.md`)
- Extension user → Background coordinator: browses (evidence: `README.md`)
- Background coordinator → Page protections: enforces protections
- Page protections → DNT and GPC signals: sends signals (evidence: `README.md`)
- Tracker learning → Privacy state: records decisions
- Request handling → First-party mapping: checks ownership
- Page protections → Fingerprint defenses: blocks tracking
- Page protections → Storage protections: protects storage
- Widget replacements → Surrogate dispatch: provides replacements (evidence: `README.md`)
- Page protections → Social link cleaning: cleans links (evidence: `README.md`)
