# bengmoh/filter-video architecture

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

- Interactive diagram: https://gitdiagram.com/bengmoh/filter-video
- Repository: https://github.com/bengmoh/filter-video

## Overview

##### Main Components
- Browser Extension Core: This is the overall client-side extension that manifests in the browser. It consists of multiple parts:
- Manifest (src/manifest.json and firefox/manifest.json): Declares the extension’s permissions, scripts, and settings.
- Background Script (src/background.js): Manages long-running background processes (e.g., listening for events, managing state).
- Content Script (src/content.js): Injected into web pages; responsible for detecting video elements and applying filters.
- Popup/Interaction UI:
- Popup UI (src/popup folder with popup.html, popup.js, and popup.scss): The front-end interface that the user interacts with from the browser toolbar.
- Utilities and Services:
- Key Mapping (src/utils/KeyMapping.js): Handles customizable shortcut keys including the special mapping between English and Arabic keyboards.
- Video Detection (src/utils/VideoDetection.js): Contains logic to detect videos within a web page and even handle iframe cases.
- Testing Layer:
- Test Scripts (tests folder): Used to validate extension functionality (e.g., extension.test.js and test setup).

##### Relationships and Interactions
- The manifest files dictate that when the extension is loaded, the background script and content script are activated.
- The background script may manage extension-wide state (for enabling/disabling, persisting settings using storage, etc.).
- The content script communicates directly with webpage DOM elements, leveraging the VideoDetection utility to identify video elements. When a video is detected, it might signal to the background or directly to the popup UI.
- The popup UI offers controls like filtering intensities and keyboard customization. The popup interacts with the background through messaging or reads/writes persistent settings.
- Utility modules (KeyMapping and VideoDetection) are shared across components to ensure consistent behavior when toggling filters based on key events.
- The build configuration files (webpack, babel) and test configurations (jest) drive the build and validate the code but are outside the runtime architecture.

##### Important Architectural Patterns and Principles to Capture
- Separation of Concerns: Clearly divide the extension’s functionality into presentation (popup), background processing, and webpage manipulation (content script).
- Event-Driven Architecture: Emphasize that the design is event-based – triggered by user keyboard shortcuts, video detections, or browser events (like tab updates).
- Modular Design: Illustrate that utility modules (KeyMapping, VideoDetection) encapsulate core logic shared across components.
- Cross-Platform Considerations: Note the dual manifest setup and handling differences between Chrome and Firefox.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Extension Core
    subgraph "Browser Extension Core"
        CM["Chrome Manifest"]:::config
        FM["Firefox Manifest"]:::config
        BS["Background Script"]:::script
        CS["Content Script"]:::script
    end

    %% Popup/Interaction UI
    subgraph "Popup/Interaction UI"
        PH["Popup HTML"]:::ui
        PL["Popup Logic"]:::ui
        PS["Popup Styles"]:::ui
    end

    %% Utilities and Services
    subgraph "Utilities and Services"
        KM["Key Mapping Module"]:::utility
        VD["Video Detection Module"]:::utility
    end

    %% Testing Layer
    subgraph "Testing Layer"
        TS["Test Scripts"]:::test
    end

    %% Connections: Manifest activates scripts
    CM -->|"activates"| BS
    CM -->|"activates"| CS
    FM -->|"activates"| BS
    FM -->|"activates"| CS

    %% Content Script interactions
    CS -->|"detects-video"| VD
    CS -->|"processes-key"| KM

    %% Popup UI interactions
    PL -->|"sends-controls"| BS
    PL -->|"utilizes-keymap"| KM
    PL -->|"updates-display"| PH

    %% Additional interaction: Background updating popup
    BS -->|"updates-settings"| PL

    %% Styles
    classDef config fill:#ffe6cc,stroke:#d79f00,stroke-width:2px;
    classDef script fill:#cce5ff,stroke:#3399ff,stroke-width:2px;
    classDef ui fill:#e6ffe6,stroke:#33cc33,stroke-width:2px;
    classDef utility fill:#fff2cc,stroke:#e6b800,stroke-width:2px;
    classDef test fill:#f9d6d5,stroke:#e06666,stroke-width:2px;

    %% Click Events
    click CM "https://github.com/bengmoh/filter-video/blob/main/src/manifest.json"
    click FM "https://github.com/bengmoh/filter-video/blob/main/firefox/manifest.json"
    click BS "https://github.com/bengmoh/filter-video/blob/main/src/background.js"
    click CS "https://github.com/bengmoh/filter-video/blob/main/src/content.js"
    click PH "https://github.com/bengmoh/filter-video/blob/main/src/popup/popup.html"
    click PL "https://github.com/bengmoh/filter-video/blob/main/src/popup/popup.js"
    click PS "https://github.com/bengmoh/filter-video/blob/main/src/popup/popup.scss"
    click KM "https://github.com/bengmoh/filter-video/blob/main/src/utils/KeyMapping.js"
    click VD "https://github.com/bengmoh/filter-video/blob/main/src/utils/VideoDetection.js"
    click TS "https://github.com/bengmoh/filter-video/tree/main/tests/"
```
