# meistyr/winnower-adblock architecture

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

- Interactive diagram: https://gitdiagram.com/meistyr/winnower-adblock
- Repository: https://github.com/meistyr/winnower-adblock

## Overview

winnower is a Chromium content blocker. A page load is handled by the extension service worker and content scripts: network rules block requests, while page-side cosmetic rules and site fixes hide unwanted content; a separate popup guard handles popunders. Users manage site and list switches and inspect diagnostics in the toolbar popup. The README documents capabilities beyond the sampled code; those branches are shown at the documented subsystem level. Arrows use README statements or source excerpts/index references; unsampled implementation details are not inferred.

Main entry points: [`src/sw.ts`](https://github.com/meistyr/winnower-adblock/blob/main/src/sw.ts) (Service worker), [`src/popup.ts`](https://github.com/meistyr/winnower-adblock/blob/main/src/popup.ts) (Toolbar popup), [`src/content.ts`](https://github.com/meistyr/winnower-adblock/blob/main/src/content.ts) (Content script), [`src/collapse.ts`](https://github.com/meistyr/winnower-adblock/blob/main/src/collapse.ts) (Empty-box collapser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Extension control"]
  node_worker["Service worker<br/>[sw.ts]"]
  node_menu["Toolbar popup<br/>[popup.ts]"]
  node_settings[("Site and list settings<br/>[sw.ts]")]
end

subgraph group_filtering["Page filtering"]
  node_content["Content script<br/>[content.ts]"]
  node_cosmetic["Cosmetic rules<br/>[sw.ts]"]
  node_rules[("Network rulesets<br/>[sw.ts]")]
  node_sitefix["Site fixes<br/>[sw.ts]"]
  node_collapse["Empty-box collapser<br/>[collapse.ts]"]
end

subgraph group_popup["Popup blocking"]
  node_popguard["Popup guard<br/>[popup-guard.ts]"]
end

subgraph group_diagnostics["Diagnostics"]
  node_report["Page reporter<br/>[report.ts]"]
  node_log["Diagnostic log<br/>[log.ts]"]
  node_logstore[("Session log storage<br/>[sw.ts]")]
end

subgraph group_shared["Shared runtime"]
  node_collapsejudge["Collapse judgement<br/>[collapse-match.ts]"]
  node_popupjudge["Popup matcher<br/>[popup-match.ts]"]
  node_protocol["Message protocol<br/>[messages.ts]"]
  node_catalogue["Ruleset catalogue<br/>[catalogue.ts]"]
end

node_user(("Browser user"))
node_browser["Chromium browser"]
node_github["GitHub releases API"]

node_user -->|"opens and controls"| node_menu
node_browser -->|"runs extension"| node_worker
node_browser -->|"injects on pages"| node_content
node_menu -->|"sends commands"| node_worker
node_content -->|"requests selectors"| node_worker
node_worker -->|"serves selectors"| node_cosmetic
node_worker -->|"controls rule sets"| node_rules
node_worker -->|"registers fixes"| node_sitefix
node_content -->|"starts"| node_collapse
node_collapse -->|"judges boxes"| node_collapsejudge
node_content -->|"records decisions"| node_report
node_collapse -->|"reports outcomes"| node_report
node_report -->|"sends log batches"| node_worker
node_worker -->|"persists session log"| node_logstore
node_menu -->|"formats diagnostics"| node_log
node_menu -.->|"manages popup settings"| node_popguard
node_popguard -->|"matches popup hosts"| node_popupjudge
node_worker -->|"uses ruleset types"| node_catalogue
node_menu -->|"renders list controls"| node_catalogue
node_worker -->|"checks releases"| node_github

click node_worker "https://github.com/meistyr/winnower-adblock/blob/main/src/sw.ts"
click node_menu "https://github.com/meistyr/winnower-adblock/blob/main/src/popup.ts"
click node_content "https://github.com/meistyr/winnower-adblock/blob/main/src/content.ts"
click node_cosmetic "https://github.com/meistyr/winnower-adblock/blob/main/src/sw.ts"
click node_rules "https://github.com/meistyr/winnower-adblock/blob/main/src/sw.ts"
click node_sitefix "https://github.com/meistyr/winnower-adblock/blob/main/src/sw.ts"
click node_collapse "https://github.com/meistyr/winnower-adblock/blob/main/src/collapse.ts"
click node_collapsejudge "https://github.com/meistyr/winnower-adblock/blob/main/src/shared/collapse-match.ts"
click node_popguard "https://github.com/meistyr/winnower-adblock/blob/main/src/popup-guard.ts"
click node_popupjudge "https://github.com/meistyr/winnower-adblock/blob/main/src/shared/popup-match.ts"
click node_settings "https://github.com/meistyr/winnower-adblock/blob/main/src/sw.ts"
click node_protocol "https://github.com/meistyr/winnower-adblock/blob/main/src/shared/messages.ts"
click node_catalogue "https://github.com/meistyr/winnower-adblock/blob/main/src/shared/catalogue.ts"
click node_report "https://github.com/meistyr/winnower-adblock/blob/main/src/report.ts"
click node_log "https://github.com/meistyr/winnower-adblock/blob/main/src/shared/log.ts"
click node_logstore "https://github.com/meistyr/winnower-adblock/blob/main/src/sw.ts"

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_worker,node_menu,node_settings,node_user,node_browser toneBlue
class node_content,node_cosmetic,node_rules,node_sitefix,node_collapse toneAmber
class node_popguard,node_github toneMint
class node_report,node_log,node_logstore toneRose
class node_collapsejudge,node_popupjudge,node_protocol,node_catalogue toneIndigo
```

## Components

### Extension control

- [Service worker](https://github.com/meistyr/winnower-adblock/blob/main/src/sw.ts): `src/sw.ts`
- [Toolbar popup](https://github.com/meistyr/winnower-adblock/blob/main/src/popup.ts): `src/popup.ts`
- [Site and list settings](https://github.com/meistyr/winnower-adblock/blob/main/src/sw.ts): `src/sw.ts`

### Page filtering

- [Content script](https://github.com/meistyr/winnower-adblock/blob/main/src/content.ts): `src/content.ts`
- [Cosmetic rules](https://github.com/meistyr/winnower-adblock/blob/main/src/sw.ts): `src/sw.ts`
- [Network rulesets](https://github.com/meistyr/winnower-adblock/blob/main/src/sw.ts): `src/sw.ts`
- [Site fixes](https://github.com/meistyr/winnower-adblock/blob/main/src/sw.ts): `src/sw.ts`
- [Empty-box collapser](https://github.com/meistyr/winnower-adblock/blob/main/src/collapse.ts): `src/collapse.ts`

### Popup blocking

- [Popup guard](https://github.com/meistyr/winnower-adblock/blob/main/src/popup-guard.ts): `src/popup-guard.ts`

### Diagnostics

- [Page reporter](https://github.com/meistyr/winnower-adblock/blob/main/src/report.ts): `src/report.ts`
- [Diagnostic log](https://github.com/meistyr/winnower-adblock/blob/main/src/shared/log.ts): `src/shared/log.ts`
- [Session log storage](https://github.com/meistyr/winnower-adblock/blob/main/src/sw.ts): `src/sw.ts`

### Shared runtime

- [Collapse judgement](https://github.com/meistyr/winnower-adblock/blob/main/src/shared/collapse-match.ts): `src/shared/collapse-match.ts`
- [Popup matcher](https://github.com/meistyr/winnower-adblock/blob/main/src/shared/popup-match.ts): `src/shared/popup-match.ts`
- [Message protocol](https://github.com/meistyr/winnower-adblock/blob/main/src/shared/messages.ts): `src/shared/messages.ts`
- [Ruleset catalogue](https://github.com/meistyr/winnower-adblock/blob/main/src/shared/catalogue.ts): `src/shared/catalogue.ts`

### Other components

- **Browser user**
- **Chromium browser**
- **GitHub releases API**

## Connections

- Browser user → Toolbar popup: opens and controls (evidence: `README.md`)
- Chromium browser → Service worker: runs extension (evidence: `README.md`)
- Chromium browser → Content script: injects on pages (evidence: `src/content.ts`)
- Toolbar popup → Service worker: sends commands (evidence: `src/popup.ts`)
- Content script → Service worker: requests selectors (evidence: `src/content.ts`)
- Service worker → Cosmetic rules: serves selectors (evidence: `src/sw.ts`)
- Service worker → Network rulesets: controls rule sets (evidence: `README.md`)
- Service worker → Site fixes: registers fixes (evidence: `README.md`)
- Content script → Empty-box collapser: starts (evidence: `src/content.ts`)
- Empty-box collapser → Collapse judgement: judges boxes (evidence: `src/collapse.ts`)
- Content script → Page reporter: records decisions (evidence: `src/content.ts`)
- Empty-box collapser → Page reporter: reports outcomes (evidence: `src/collapse.ts`)
- Page reporter → Service worker: sends log batches (evidence: `src/report.ts`)
- Service worker → Session log storage: persists session log (evidence: `src/sw.ts`)
- Toolbar popup → Diagnostic log: formats diagnostics (evidence: `src/popup.ts`)
- Toolbar popup → Popup guard: manages popup settings
- Popup guard → Popup matcher: matches popup hosts (evidence: `src/popup-guard.ts`)
- Service worker → Ruleset catalogue: uses ruleset types (evidence: `src/sw.ts`)
- Toolbar popup → Ruleset catalogue: renders list controls (evidence: `src/popup.ts`)
- Service worker → GitHub releases API: checks releases (evidence: `src/sw.ts`)