# ghoulishg/organicsearchresultshighlighter architecture

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

- Interactive diagram: https://gitdiagram.com/ghoulishg/organicsearchresultshighlighter
- Repository: https://github.com/ghoulishg/organicsearchresultshighlighter

## Overview

1. **What this repo is**
   - This is a **Chrome/Chromium extension** called **Organic Results Highlighter**.
   - Its architecture is split between a **page-injected content script** that operates inside Google/Bing search result pages and a **popup UI** that lets the user configure behavior.

2. **Primary runtime surfaces**
   - `manifest.json` is the central boundary definition: it declares which pages the extension runs on, which scripts/styles are injected, and what local storage/extension permissions are needed.
   - The extension has two main execution contexts:
     - **Search tab context**: `content.js` + `content.css`
     - **Extension popup context**: `popup.html` + `popup.js` + `popup.css`

3. **Content script subsystem**
   - `content.js` is the main automation engine.
   - It detects organic search results on Google and Bing, applies highlight classes/styles, and keeps working as the page changes.
   - Because it runs inside the page, it is the boundary between the extension and third-party DOMs; all search-engine-specific selector logic lives here.

4. **Dynamic page monitoring**
   - The extension is built for **live search result pages**, not static HTML.
   - A debounced `MutationObserver` watches for DOM updates caused by infinite scroll, AJAX loading, and result re-rendering.
   - That observer is the main data flow trigger: when search results change, the script re-scans the page and updates highlights without requiring a refresh.

5. **Selector-based detection model**
   - The repo emphasizes **CSS selector configuration** as the core abstraction for identifying organic results.
   - Default selectors are tuned for Google/Bing, and the advanced settings allow users to override them if markup changes.
   - This means the detection layer is intentionally decoupled from the popup UI and stored configuration, so selector updates can be applied without redeploying code.

6. **Noise filtering and scope control**
   - The content script does not blindly style every result-looking element.
   - It explicitly filters out ads, sidebars, auxiliary panels, “People Also Ask,” and nested sub-elements to avoid false positives.
   - Architecturally, this is the extension’s main correctness boundary: it distinguishes “organic result cards” from surrounding search-page chrome.

7. **Styling subsystem**
   - `content.css` contains the visual treatment for highlighted results, including soft pastel backgrounds and any pulse/verification animation.
   - This keeps presentation separate from detection logic: `content.js` decides *what* to style, while `content.css` defines *how* it looks.

8. **Popup/settings subsystem**
   - `popup.html` defines the user-facing control surface.
   - `popup.js` manages theme selection, live counter display, verification scan actions, and advanced selector edits.
   - `popup.css` provides the glassmorphism-themed UI and theme styling.
   - This popup is the control plane for the extension; it does not process search pages directly, but it changes the content script’s behavior through shared state.

9. **Persistent configuration and state**
   - The readme indicates settings are stored locally in `chrome.storage.local`.
   - That storage is the bridge between the popup and content script: popup writes preferences, content script reads them when deciding selectors, themes, and other options.
   - The architecture is privacy-preserving because there is no backend, no network sync, and no external API dependency.

10. **Live count and verification flow**
   - The live highlight counter and verification scan are feedback mechanisms layered on top of the detection pipeline.
   - The count is derived from the current set of highlighted DOM nodes.
   - Verification briefly pulses the styled elements so the user can confirm the selector set is matching the intended page regions.

11. **Assets and packaging**
   - `icons/` contains the extension artwork used by Chrome.
   - `generate_icons.ps1` is a build-time utility for producing those assets; it is not part of the runtime architecture.
   - The repo otherwise stays intentionally lightweight and vanilla—no external libraries or backend services.

12. **Overall data flow**
   - User opens a Google/Bing results page → Chrome injects `content.js` and `content.css` per `manifest.json` → content script scans DOM and highlights organic results → `MutationObserver` keeps the highlights current → user opens the popup to switch themes or adjust selectors → popup writes settings to local storage → content script reads those settings and updates its matching/styling behavior.

13. **Key architectural boundary to diagram**
   - The most important boundary is **extension code vs. third-party search-page DOM**.
   - Everything else is internal orchestration around that boundary: popup configuration, local persistence, and CSS presentation.
   - There is no server component, so the architecture is fully client-side and browser-contained.

Main entry points: [`popup.js`](https://github.com/ghoulishg/organicsearchresultshighlighter/blob/main/popup.js) (Popup logic), [`content.js`](https://github.com/ghoulishg/organicsearchresultshighlighter/blob/main/content.js) (Content script), [`manifest.json`](https://github.com/ghoulishg/organicsearchresultshighlighter/blob/main/manifest.json) (Manifest), [`popup.html`](https://github.com/ghoulishg/organicsearchresultshighlighter/blob/main/popup.html) (Popup shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_extension["Extension runtime"]
  node_manifest["Manifest<br/>[manifest.json]"]
  node_storage[("Local storage<br/>persistent config")]
end

subgraph group_group_search["Search tab"]
  node_search_boundary["Search DOM<br/>third-party page"]
  node_content_js["Content script<br/>DOM highlighter<br/>[content.js]"]
  node_selectors{{"Selector logic<br/>result detection"}}
  node_observer(("DOM observer<br/>live update"))
  node_filtering{{"Noise filters<br/>scope control"}}
  node_highlights["Highlighting<br/>style application"]
  node_content_css["Content styles<br/>extension css<br/>[content.css]"]
end

subgraph group_group_popup["Popup UI"]
  node_popup_html["Popup shell<br/>extension ui<br/>[popup.html]"]
  node_popup_js["Popup logic<br/>settings controller<br/>[popup.js]"]
  node_popup_css["Popup styles<br/>ui styling<br/>[popup.css]"]
  node_theme{{"Themes<br/>ui preference"}}
  node_counter(("Live counter<br/>feedback"))
  node_verify(("Verification scan<br/>feedback action"))
end

subgraph group_group_assets["Assets"]
  node_icons["Icons<br/>packaged assets"]
end

node_manifest -->|"injects"| node_content_js
node_manifest -->|"injects"| node_content_css
node_manifest -->|"opens"| node_popup_html
node_manifest -->|"packages"| node_icons
node_manifest -->|"permits"| node_storage
node_content_js -->|"runs in"| node_search_boundary
node_content_js -->|"uses"| node_selectors
node_content_js -->|"excludes"| node_filtering
node_content_js -->|"watches"| node_observer
node_observer -->|"triggers"| node_highlights
node_selectors -->|"matches"| node_highlights
node_filtering -->|"narrows"| node_highlights
node_highlights -->|"styled by"| node_content_css
node_popup_html -->|"drives"| node_popup_js
node_popup_js -->|"styled by"| node_popup_css
node_popup_js -->|"reads/writes"| node_storage
node_popup_js -->|"selects"| node_theme
node_popup_js -->|"derives"| node_counter
node_popup_js -->|"triggers"| node_verify
node_storage -->|"feeds"| node_content_js

click node_manifest "https://github.com/ghoulishg/organicsearchresultshighlighter/blob/main/manifest.json"
click node_content_js "https://github.com/ghoulishg/organicsearchresultshighlighter/blob/main/content.js"
click node_content_css "https://github.com/ghoulishg/organicsearchresultshighlighter/blob/main/content.css"
click node_popup_html "https://github.com/ghoulishg/organicsearchresultshighlighter/blob/main/popup.html"
click node_popup_js "https://github.com/ghoulishg/organicsearchresultshighlighter/blob/main/popup.js"
click node_popup_css "https://github.com/ghoulishg/organicsearchresultshighlighter/blob/main/popup.css"
click node_icons "https://github.com/ghoulishg/organicsearchresultshighlighter/tree/main/icons"

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_manifest,node_storage toneBlue
class node_search_boundary,node_content_js,node_selectors,node_observer,node_filtering,node_highlights,node_content_css toneAmber
class node_popup_html,node_popup_js,node_popup_css,node_theme,node_counter,node_verify toneMint
class node_icons toneRose
```

## Components

### Extension runtime

Chrome extension surfaces and shared state

- [Manifest](https://github.com/ghoulishg/organicsearchresultshighlighter/blob/main/manifest.json): extension manifest · Defines permissions, injections, and page matches for the extension. · `manifest.json`
- **Local storage**: persistent config · Shared local state used to persist settings between popup and content script.

### Search tab

Injected logic running inside Google/Bing result pages

- **Search DOM**: third-party page · Google/Bing result pages that the extension reads and modifies through injected scripts.
- [Content script](https://github.com/ghoulishg/organicsearchresultshighlighter/blob/main/content.js): DOM highlighter · Scans search pages, detects organic results, applies highlights, and keeps them updated. · `content.js`
- **Selector logic**: result detection · Search-engine-specific selectors and filtering rules for organic results versus ads and page chrome.
- **DOM observer**: live update · Debounced mutation monitoring that rescans the page when results change.
- **Noise filters**: scope control · Excludes ads, sidebars, people-also-ask blocks, and nested sub-elements from highlighting.
- **Highlighting**: style application · Marks matched organic result cards in the page DOM.
- [Content styles](https://github.com/ghoulishg/organicsearchresultshighlighter/blob/main/content.css): extension css · Visual treatment for highlighted results and verification pulse effects. · `content.css`

### Popup UI

User-facing configuration and feedback controls

- [Popup shell](https://github.com/ghoulishg/organicsearchresultshighlighter/blob/main/popup.html): extension ui · Popup interface structure for extension controls and status. · `popup.html`
- [Popup logic](https://github.com/ghoulishg/organicsearchresultshighlighter/blob/main/popup.js): settings controller · Handles theme selection, live counters, verification scans, and selector edits. · `popup.js`
- [Popup styles](https://github.com/ghoulishg/organicsearchresultshighlighter/blob/main/popup.css): ui styling · Glassmorphism and theme styling for the popup interface. · `popup.css`
- **Themes**: ui preference · User-selected visual modes that affect the popup and highlight presentation.
- **Live counter**: feedback · Derived count of currently highlighted organic results.
- **Verification scan**: feedback action · Triggers a pulse/flash on matched results so the user can confirm selector accuracy.

### Assets

Packaging and icon assets

- [Icons](https://github.com/ghoulishg/organicsearchresultshighlighter/tree/main/icons): packaged assets · Chrome extension artwork bundled for browser presentation. · `icons`

## Connections

- Manifest → Content script: injects · Manifest declares content script injection on supported search pages.
- Manifest → Content styles: injects · Manifest loads page styles with the content script.
- Manifest → Popup shell: opens · Manifest defines the extension action popup surface.
- Manifest → Icons: packages · Manifest references bundled extension artwork.
- Manifest → Local storage: permits · Manifest grants access to local extension storage.
- Content script → Search DOM: runs in · Content script executes inside the search result page DOM.
- Content script → Selector logic: uses · Detection depends on search-engine-specific selectors and heuristics.
- Content script → Noise filters: excludes · Filtering logic removes ads and non-organic page regions.
- Content script → DOM observer: watches · MutationObserver drives rescans when the page updates.
- DOM observer → Highlighting: triggers · DOM changes cause highlight recalculation and refresh.
- Selector logic → Highlighting: matches · Organic result matches are turned into highlighted cards.
- Noise filters → Highlighting: narrows · Scope control ensures only intended result cards are styled.
- Highlighting → Content styles: styled by · Visual treatment is defined separately from detection logic.
- Popup shell → Popup logic: drives · Popup markup is wired to interaction logic.
- Popup logic → Popup styles: styled by · Popup logic operates within the themed popup UI.
- Popup logic → Local storage: reads/writes · Popup persists theme, selectors, and user preferences locally.
- Popup logic → Themes: selects · User theme choice updates popup and highlight presentation.
- Popup logic → Live counter: derives · Popup shows the current number of highlighted results.
- Popup logic → Verification scan: triggers · Verification action asks content script to pulse matched elements.
- Local storage → Content script: feeds · Content script reads stored settings to adapt matching and styling.