# manafasif/subreddit-blocker architecture

> Architecture diagram of the GitHub repository manafasif/subreddit-blocker, 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/manafasif/subreddit-blocker
- Repository: https://github.com/manafasif/subreddit-blocker

## Overview

##### Main Components
a. Chrome Extension Core:
- Background Scripts (background.js): Monitors browsing events and runs in the background.
- Content Script (content.js): Injected into web pages to modify or block subreddit content dynamically.
- User Interface Components:
– Popup (popup.html and popup.js): Provides quick user interaction.
– Options Page (options.html): Allows users to configure settings, such as editing the block list.
– Blocked Page (blocked.html): May be used to show a message or alternative content for blocked subreddits.
- Manifest File (manifest.json): Describes the behavior, permissions, and resources that the extension uses.
- Styling (style.css & docs/styles.css; images): For the UI elements of the extension and documentation.

b. Data Management:
- Local Block List:
– A text file (data/blocked_subreddit_names.txt) that provides the initial or allowed list of subreddits to block.
– Usage of Chrome’s local storage to save and manage this list dynamically.
- Additional Data Sources:
– JSON data files (inappropriate.json, and various files under web_scraper/data) holding information on subreddits, NSFW content, and additional metadata that might be used either by the extension or by helper utilities.

c. Utility Components for Data Extraction and Packaging:
- Web Scraper Module (web_scraper/):
– Scripts such as scraper.py, extract_subreddits.py, and evaluate_subreddits.py work to gather and evaluate subreddit data.
– Data files (e.g., all_subreddits.json, nsfw_subreddit_names.txt) used to update or validate the block list.
- Packaging and Additional Utilities:
– A Python script (utils/package_extension.py) likely used to help package the extension (an automated build step, perhaps creating a ZIP for release).

##### Relationships and Interactions
- Chrome Extension Workflow:
– The manifest file ties together all the UI components, background scripts, and content scripts, specifying their roles and permissions.
– Background.js acts as the orchestrator, invoking Chrome APIs (such as chrome.webNavigation and chrome.storage) to manage and relay changes.
– Content.js and popup.js communicate (or trigger actions) based on user interactions and page events.
– The data from the block list (read from data/blocked_subreddit_names.txt) is loaded into local storage on initialization, allowing dynamic blocking.

- Data Updating and Scraping:
– The web scraper components run separately. They fetch information from various sources (presumably Reddit) and update local JSON or text files.
– These updated data files can either be manually imported or automatically integrated into the extension’s data folder so the block list or additional metadata remains current.

- Packaging and Deployment:
– The utils/package_extension.py and zip file under releases bundle the entire extension for distribution, ensuring that all necessary components are included.

##### Architectural Patterns and Design Principles
- Modularity: Separation of the extension core from auxiliary data scraping utilities ensures that the primary blocking functionality remains lightweight and user-focused.
- Client-side Processing: By using Chrome’s local storage and content/background scripts, the extension securely processes data directly in the user’s browser.
- Extensibility: The design allows for easy updates to the block list via external files and the scraping routines.
- Clear Separation of Concerns: The division between UI (popup and options pages), logic (background and content scripts), and data management (text/JSON files and web scraper) is well maintained.

##### Relevant Technologies, Frameworks, and Libraries
- JavaScript for core extension logic.
- Chrome Extension APIs (chrome.storage, chrome.webNavigation, chrome.runtime) to interface with the browser.
- HTML/CSS for the user interface.
- Python scripts (in the web_scraper and utils directories) for data gathering, evaluation, and packaging.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Chrome Extension Core
    subgraph "Chrome Extension Core"
        %% Core Scripts
        M["Manifest (manifest.json)"]
        B["Background Script (background.js)"]
        C["Content Script (content.js)"]
        
        M -->|"loads"| B
        M -->|"loads"| C
        
        %% User Interface Components
        subgraph "User Interface"
            PHTML["Popup UI HTML (popup.html)"]
            PSCRIPT["Popup UI Script (popup.js)"]
            O["Options Page (options.html)"]
            BL["Blocked Page (blocked.html)"]
            ST["Style (style.css)"]
            DST["Docs Style (docs/styles.css)"]
            IMG["Images (images)"]
        end
        
        %% Data Management Components
        subgraph "Data Management"
            LBS["Local Block List (blocked_subreddit_names.txt)"]
            AD["Additional Data (inappropriate.json)"]
        end
        
        %% Manifest links to UI Components
        M -->|"registers"| PHTML
        M -->|"registers"| PSCRIPT
        M -->|"registers"| O
        M -->|"registers"| BL
        M -->|"registers"| ST
        M -->|"registers"| DST
        M -->|"registers"| IMG
        
        %% UI and background interaction
        PHTML -->|"triggers"| B
        PSCRIPT -->|"triggers"| B
        O -->|"updates"| LBS
        
        %% Data flow into core logic
        LBS -->|"feeds"| B
        AD -->|"feeds"| B
        
        %% Communication between background and content scripts
        B -->|"communicates"| C
    end

    %% Data Scraper & Packaging Utility
    subgraph "Data Scraper & Packaging Utility"
        %% Web Scraper Module
        subgraph "Web Scraper Module"
            SP1["scraper.py"]
            SP2["extract_subreddits.py"]
            SP3["extract_all_subreddit_info.py"]
            SP4["evaluate_subreddits.py"]
        end
        WSD["Web Scraper Data Files (web_scraper/data/)"]
        PS["Packaging Script (package_extension.py)"]
        RP["Release Package (SubReddit_Blocker.zip)"]
        
        %% Web Scraper Module outputs data files
        SP1 --> WSD
        SP2 --> WSD
        SP3 --> WSD
        SP4 --> WSD
        
        %% Web scraper data updates the block list in the extension
        WSD -->|"updates"| LBS

        %% Packaging flows
        PS --> RP
    end

    %% Styles for diagram components
    classDef ui fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef logic fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef data fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef utility fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef manifest fill:#B2DFDB,stroke:#00796B,stroke-width:2px;

    class M manifest;
    class B,C logic;
    class PHTML,PSCRIPT,O,BL,ST,DST,IMG ui;
    class LBS,AD data;
    class SP1,SP2,SP3,SP4,PS,RP,WSD utility;

%% Click Events
click M "https://github.com/manafasif/subreddit-blocker/blob/main/manifest.json"
click B "https://github.com/manafasif/subreddit-blocker/blob/main/background.js"
click C "https://github.com/manafasif/subreddit-blocker/blob/main/content.js"
click PHTML "https://github.com/manafasif/subreddit-blocker/blob/main/popup.html"
click PSCRIPT "https://github.com/manafasif/subreddit-blocker/blob/main/popup.js"
click O "https://github.com/manafasif/subreddit-blocker/blob/main/options.html"
click BL "https://github.com/manafasif/subreddit-blocker/blob/main/blocked.html"
click ST "https://github.com/manafasif/subreddit-blocker/blob/main/style.css"
click DST "https://github.com/manafasif/subreddit-blocker/blob/main/docs/styles.css"
click IMG "https://github.com/manafasif/subreddit-blocker/tree/main/images"
click LBS "https://github.com/manafasif/subreddit-blocker/blob/main/data/blocked_subreddit_names.txt"
click AD "https://github.com/manafasif/subreddit-blocker/blob/main/inappropriate.json"
click SP1 "https://github.com/manafasif/subreddit-blocker/blob/main/web_scraper/scraper.py"
click SP2 "https://github.com/manafasif/subreddit-blocker/blob/main/web_scraper/extract_subreddits.py"
click SP3 "https://github.com/manafasif/subreddit-blocker/blob/main/web_scraper/extract_all_subreddit_info.py"
click SP4 "https://github.com/manafasif/subreddit-blocker/blob/main/web_scraper/evaluate_subreddits.py"
click WSD "https://github.com/manafasif/subreddit-blocker/tree/main/web_scraper/data/"
click PS "https://github.com/manafasif/subreddit-blocker/blob/main/utils/package_extension.py"
click RP "https://github.com/manafasif/subreddit-blocker/blob/main/releases/SubReddit_Blocker.zip"
```
