# divij-agarwal-42/youtube-detoxifier architecture

> Architecture diagram of the GitHub repository divij-agarwal-42/youtube-detoxifier, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/divij-agarwal-42/youtube-detoxifier
- Repository: https://github.com/divij-agarwal-42/youtube-detoxifier

## Overview

##### Project Type and Purpose
- This is a Chrome browser extension (“Youtube Detoxifier”) designed to modify the YouTube user interface in real time.
- It provides three main features:
- Hiding video recommendations and comments
- A timeout/auto‑pause feature to limit watch time
- A “break” mode to temporarily suspend the blocking rules

##### File Structure Analysis
- manifest.json
- The extension’s metadata, permissions (tabs, storage), and registration of content/background scripts and UI pages.
- background.js
- Persistent event handler; coordinates timer logic, break mode, and message routing.
- content.js
- Injected into YouTube pages; manipulates the DOM to hide comments, recommendations, shorts.
- popup.html, popup.js, popup.css
- The browser‑action (toolbar) UI; allows users to toggle features, set timeout and break durations.
- landing_page.html, landing_page.js, landing_page.css
- The options or welcome page (opened via popup link or context menu) for extended configuration.
- timer.html, timerscript.js, timerstyles.css
- A standalone timer page (could be opened in a new tab) showing the countdown UI.
- reading-time_images/

##### Key Architectural Patterns
- Event‑driven architecture utilizing Chrome’s extension message passing.
- Separation of concerns:
- UI layer (popup/landing_page/timer pages)
- Background controller (background.js)
- Content manipulation (content.js)
- Browser storage (chrome.storage) for persisting user settings.

##### Main Components
a. Browser Host
- Chrome runtime environment provides APIs (storage, messaging, tabs)
b. Manifest Module
- Registers content and background scripts, UI pages, and permissions
c. Background Service (background.js)
- Listens for user actions from the popup or timer
- Starts/stops timers and break periods
- Routes messages between UI and content scripts
d. Content Script (content.js)
- Injected into every youtube.com tab
- Hides or shows page elements based on current settings
e. Popup UI (popup.html/js/css)
- Toolbar interface for toggling features and setting durations
f. Landing/Options Page (landing_page.html/js/css)
- Extended configuration and informational display
g. Timer View (timer.html/js/css)
- Dedicated countdown display when a timeout is active
h. Chrome Storage
- Persists user preferences (enabled features, timeout length, break status)
i. YouTube Page (External Service)
- Destination website where DOM manipulations occur

##### Interactions and Data Flows
→ Popup sends message to Background Service
→ Background writes to Storage and relays command to active Content Scripts
→ Content Scripts update the YouTube page DOM
- For timer: Background Service starts countdown → Updates Timer View if open → On timeout expiry → Sends “disable” message to Content Scripts
- Break mode: User triggers break via Popup → Background flips a flag in Storage → Content Scripts read new flag on next message or page reload

##### Final Advice
- Be exhaustive: include manifest.json as the binding point for all scripts/pages.
- Runtime lifecycle: content scripts load on page load, background persists across tabs, UIs load on user demand.
- Keep the layout simple: arrange Browser Host at the top, Storage in the center, and other components radiating around.

## Diagram (Mermaid)

```mermaid
flowchart TD
    BH["Chrome Host (Chrome Runtime)"]:::host
    MF["manifest.json"]:::manifest
    BS["Background Service"]:::background
    ST[(Chrome Storage)]:::storage

    subgraph "UI Components"
        PUI["Popup UI"]:::ui
        LOP["Landing/Options Page"]:::ui
        TV["Timer View"]:::ui
        AS["Assets"]:::assets
    end

    subgraph "YouTube Tab"
        CS["Content Script"]:::content
        YT(("YouTube Page")):::external
    end

    BH --> MF
    MF --> BS
    MF --> CS
    MF --> PUI
    MF --> LOP
    MF --> TV

    PUI -->|"sendMessage"| BS
    LOP -->|"sendMessage"| BS
    TV -->|"sendMessage"| BS

    BS -->|"read/write"| ST
    BS -->|"control (setTimeout, toggleBreak)"| CS
    BS -->|"updateCountdown"| TV

    CS -->|"hideComments/recommendations"| YT

    classDef host fill:#e0f7fa,stroke:#006064,color:#004d40;
    classDef manifest fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c;
    classDef background fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20;
    classDef ui fill:#e3f2fd,stroke:#1565c0,color:#0d47a1;
    classDef content fill:#fff3e0,stroke:#ef6c00,color:#e65100;
    classDef storage fill:#eceff1,stroke:#607d8b,color:#37474f;
    classDef external fill:#ffffff,stroke:#b0bec5,color:#546e7a,stroke-dasharray: 5 5;
    classDef assets fill:#fce4ec,stroke:#ad1457,color:#880e4f;

    click MF "https://github.com/divij-agarwal-42/youtube-detoxifier/blob/main/manifest.json"
    click BS "https://github.com/divij-agarwal-42/youtube-detoxifier/blob/main/background.js"
    click CS "https://github.com/divij-agarwal-42/youtube-detoxifier/blob/main/content.js"
    click PUI "https://github.com/divij-agarwal-42/youtube-detoxifier/blob/main/popup.html"
    click LOP "https://github.com/divij-agarwal-42/youtube-detoxifier/blob/main/landing_page.html"
    click TV "https://github.com/divij-agarwal-42/youtube-detoxifier/blob/main/timer.html"
    click AS "https://github.com/divij-agarwal-42/youtube-detoxifier/tree/main/reading-time_images/"
```
