# z4kkyhub/chrome-ext-youtube-focus-suite architecture

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

- Interactive diagram: https://gitdiagram.com/z4kkyhub/chrome-ext-youtube-focus-suite
- Repository: https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite

## Overview

#### Purpose and Extension Entry Points
YouTube Focus Suite is a Manifest V3 Chrome extension that combines two independently toggled YouTube behaviors: distraction-reduced video viewing and Shorts removal/redirecting. Chrome loads the extension definition from `manifest.json`; its runtime entry points are the service worker `background.js`, toolbar popup `popup/popup.html`, and YouTube content scripts under `content/`.

#### Manifest and Runtime Topology
`manifest.json` defines the extension’s permissions, host matching, content-script injection, popup, and declarative rules integration. The browser executes `background.js` in the MV3 service-worker lifecycle, injects feature-specific scripts/CSS into applicable YouTube pages, and opens `popup/popup.html` as the user-facing settings surface.

#### Focus Mode Feature
Focus mode targets video-watch pages and removes related videos, comments, and supporting UI through page-level CSS and DOM behavior:
- `content/focus-mode.js`
- `content/focus-mode.css`

The content script applies or removes the focus presentation based on persisted state and exposes an in-page control near the video player. This is the feature boundary most coupled to YouTube’s changing DOM structure.

#### Shorts Suppression Feature
Shorts removal is split between regular-page filtering and direct-navigation prevention:
- `content/hide-shorts.js`
- `content/hide-shorts.css`
- `rules/shorts-redirect.json`

The content layer hides Shorts cards/sections across home, subscriptions, search, and related-content surfaces. Declarative network rules redirect navigations to `/shorts/*` back to the home page, avoiding a content-script-only redirect path.

#### Settings and User Control Flow
The toolbar UI in `popup/popup.html` and `popup/popup.js` lets users toggle Focus Mode and Hide Shorts separately; styling is contained in `popup/popup.css`. State is stored in Chrome sync storage, so popup changes propagate to content-script behavior across signed-in Chrome instances. Focus Mode additionally accepts page-local toggling through its injected video-page button.

#### Background Coordination and Platform Boundaries
`background.js` is the privileged extension-side coordinator for browser events, state defaults or updates, and ruleset enablement as required by the Shorts setting. Content scripts operate within YouTube page contexts and should limit responsibility to DOM observation/manipulation. Chrome extension APIs—especially synchronized storage and declarative network request rules—form the key boundary between persistent settings, browser-level navigation handling, and page-level UI changes.

#### Infrastructure and Maintenance Constraints
This is a client-only browser extension: no backend, database, or external API service is indicated. It relies on Chrome/Chromium extension APIs and YouTube’s rendered DOM. The primary operational risk is YouTube markup changes; selectors and DOM handling in `content/focus-mode.js` and `content/hide-shorts.js` are the likely maintenance points.

Main entry points: [`manifest.json`](https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/manifest.json) (Extension manifest), [`content/focus-mode.js`](https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/content/focus-mode.js) (Focus Mode), [`content/hide-shorts.js`](https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/content/hide-shorts.js) (Hide Shorts), [`background.js`](https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/background.js) (Background coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Extension runtime"]
  node_manifest["Extension manifest<br/>MV3 definition<br/>[manifest.json]"]
  node_background["Background coordinator<br/>service worker<br/>[background.js]"]
  node_chrome_storage[("Sync settings<br/>Chrome storage API")]
  node_network_rules["Declarative rules<br/>Chrome DNR API"]
  node_shorts_rules["Shorts redirect rules<br/>ruleset"]
end

subgraph group_popup["Toolbar settings"]
  node_popup_html["Settings popup<br/>popup page<br/>[popup.html]"]
  node_popup_js["Popup controls<br/>popup script<br/>[popup.js]"]
  node_popup_css["Popup styling<br/>popup stylesheet<br/>[popup.css]"]
end

subgraph group_youtube["YouTube page layer"]
  node_focus_script["Focus Mode<br/>content script<br/>[focus-mode.js]"]
  node_focus_css["Focus presentation<br/>content stylesheet<br/>[focus-mode.css]"]
  node_shorts_script["Hide Shorts<br/>content script<br/>[hide-shorts.js]"]
  node_shorts_css["Shorts filtering<br/>content stylesheet<br/>[hide-shorts.css]"]
  node_youtube_dom["YouTube rendered DOM<br/>page context"]
end

node_manifest -->|"starts"| node_background
node_manifest -->|"opens as toolbar popup"| node_popup_html
node_manifest -->|"injects on watch pages"| node_focus_script
node_manifest -->|"injects on YouTube pages"| node_shorts_script
node_manifest -->|"registers ruleset"| node_shorts_rules
node_popup_html -->|"loads"| node_popup_js
node_popup_html -->|"styles with"| node_popup_css
node_popup_js -->|"updates toggles"| node_chrome_storage
node_background -->|"initializes and coordinates"| node_chrome_storage
node_background -->|"enables by Shorts setting"| node_network_rules
node_network_rules -->|"activates"| node_shorts_rules
node_focus_script -->|"reads and updates Focus state"| node_chrome_storage
node_shorts_script -->|"reads Hide Shorts state"| node_chrome_storage
node_focus_script -->|"applies"| node_focus_css
node_shorts_script -->|"applies"| node_shorts_css
node_focus_script -->|"manipulates watch-page UI"| node_youtube_dom
node_shorts_script -->|"hides Shorts surfaces"| node_youtube_dom

click node_manifest "https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/manifest.json"
click node_background "https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/background.js"
click node_shorts_rules "https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/rules/shorts-redirect.json"
click node_popup_html "https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/popup/popup.html"
click node_popup_js "https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/popup/popup.js"
click node_popup_css "https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/popup/popup.css"
click node_focus_script "https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/content/focus-mode.js"
click node_focus_css "https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/content/focus-mode.css"
click node_shorts_script "https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/content/hide-shorts.js"
click node_shorts_css "https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/content/hide-shorts.css"

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_background,node_chrome_storage,node_network_rules,node_shorts_rules toneBlue
class node_popup_html,node_popup_js,node_popup_css toneAmber
class node_focus_script,node_focus_css,node_shorts_script,node_shorts_css,node_youtube_dom toneMint
```

## Components

### Extension runtime

- [Extension manifest](https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/manifest.json): MV3 definition · Declares entry points, permissions, injection, and rules. · `manifest.json`
- [Background coordinator](https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/background.js): service worker · Coordinates defaults, browser events, and ruleset state. · `background.js`
- **Sync settings**: Chrome storage API · Persists independently toggled feature settings.
- **Declarative rules**: Chrome DNR API · Applies browser-level Shorts navigation handling.
- [Shorts redirect rules](https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/rules/shorts-redirect.json): ruleset · Redirects /shorts/ navigations to home. · `rules/shorts-redirect.json`

### Toolbar settings

- [Settings popup](https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/popup/popup.html): popup page · Toolbar surface for both feature toggles. · `popup/popup.html`
- [Popup controls](https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/popup/popup.js): popup script · Reads and updates feature settings. · `popup/popup.js`
- [Popup styling](https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/popup/popup.css): popup stylesheet · `popup/popup.css`

### YouTube page layer

- [Focus Mode](https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/content/focus-mode.js): content script · Controls watch-page UI and in-page toggle. · `content/focus-mode.js`
- [Focus presentation](https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/content/focus-mode.css): content stylesheet · Hides related videos, comments, and supporting UI. · `content/focus-mode.css`
- [Hide Shorts](https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/content/hide-shorts.js): content script · Filters Shorts surfaces across YouTube pages. · `content/hide-shorts.js`
- [Shorts filtering](https://github.com/z4kkyhub/chrome-ext-youtube-focus-suite/blob/main/content/hide-shorts.css): content stylesheet · `content/hide-shorts.css`
- **YouTube rendered DOM**: page context · Selector-sensitive target for content scripts.

## Connections

- Extension manifest → Background coordinator: starts
- Extension manifest → Settings popup: opens as toolbar popup
- Extension manifest → Focus Mode: injects on watch pages
- Extension manifest → Hide Shorts: injects on YouTube pages
- Extension manifest → Shorts redirect rules: registers ruleset
- Settings popup → Popup controls: loads
- Settings popup → Popup styling: styles with
- Popup controls → Sync settings: updates toggles
- Background coordinator → Sync settings: initializes and coordinates
- Background coordinator → Declarative rules: enables by Shorts setting
- Declarative rules → Shorts redirect rules: activates
- Focus Mode → Sync settings: reads and updates Focus state
- Hide Shorts → Sync settings: reads Hide Shorts state
- Focus Mode → Focus presentation: applies
- Hide Shorts → Shorts filtering: applies
- Focus Mode → YouTube rendered DOM: manipulates watch-page UI
- Hide Shorts → YouTube rendered DOM: hides Shorts surfaces