# ahmed-abdelwahed1/x-unbookmarker architecture

> Architecture diagram of the GitHub repository ahmed-abdelwahed1/x-unbookmarker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahmed-abdelwahed1/x-unbookmarker
- Repository: https://github.com/ahmed-abdelwahed1/x-unbookmarker

## Overview

##### Project type + purpose (what you’re diagramming)
This repo is a **Chrome Extension** (Manifest-based) that runs **entirely in the user’s browser** to automate **bulk deletion of X/Twitter bookmarks**. There is **no backend service** and **no external data store**; the “system” is essentially:
- **Extension UI (popup)** for user control + progress display
- **Content script** that executes automation on `x.com/i/bookmarks`
- **Chrome Extension runtime / messaging** connecting popup ↔ content script
- **Target web app DOM** (X/Twitter Bookmarks page) as the “environment” the automation manipulates

- Chrome Extension boundary
- Web page boundary (x.com)
- Chrome APIs boundary (tabs, scripting, runtime messaging)

##### File structure analysis (map files → components)
From the tree:

- `manifest.json`
- Defines extension entry points, permissions, host matches, and which scripts run where.

- `src/popup.html`, `src/popup.js`, `src/popup.css`
- Likely contains: Start/Stop action, delay slider, progress/remaining count.

- `src/content.js`
- The **automation engine** injected into X pages (or specifically bookmarks page).
- Implements: DOM scanning for bookmarked items, click “remove bookmark”, delay logic, scrolling to load more, retry/error handling, progress reporting.

- `assets/`

- `package.json`
- Build/release tooling (even if no bundler is present).

- `.github/workflows/release.yml`, `update-version.js`
- Release automation + version bumping. Include in a separate “CI/CD & packaging” view if desired.

**Key architectural hint:** There is no `background.js` / service worker shown. That suggests a simpler architecture: popup directly communicates with content script (often via `chrome.tabs.sendMessage`) and the content script does the work.

- **Bulk remove** bookmarks
- **Custom delay** (rate-limit avoidance)
- **Real-time progress tracking**
- **Smart scrolling** (load more as you clear)
- **Error handling with retry**
- **Local processing** (explicitly show *no external servers*)

These behaviors should appear as **labeled interactions/data flows** between popup ↔ content script ↔ X DOM.

##### Popup UI
- `popup.html`
- `popup.js`
- `popup.css`
- Responsibilities: user initiates cleaning, sets delay, shows progress/errors.

##### Content Script: Bookmark Cleaner
- `content.js`
- Responsibilities:
- Detect bookmark items in DOM
- Click/unbookmark actions
- Delay/rate-limit pacing
- Retry on failure
- Scroll/load more content
- Emit progress events

##### Extension Manifest
- `manifest.json`
- Responsibility: wiring (what runs where, permissions, host access)

**Container 2: “Chrome / Extension Runtime APIs”**
##### chrome.runtime messaging
- Popup ↔ Content Script communications (commands + progress updates)
##### chrome.tabs / scripting (if used)
- Selecting active tab, ensuring content script is present, etc.

**Container 3: “X (Twitter) Website”**
##### Bookmarks Page UI / DOM
- `https://x.com/i/bookmarks`
- Includes infinite scroll feed + bookmark buttons.

##### X Network/API
- Not called directly by the extension, but indirectly by the page when DOM clicks happen.

##### User → Popup UI
- “Click Start Cleaning”
- “Adjust delay slider”

##### Popup UI → chrome.runtime messaging → Content Script
- Message: `START` with config `{delayMs}`
- Message: `STOP` (if supported)
- Message: `SET_DELAY` (if live adjustment is supported)

##### Content Script → X Bookmarks DOM
- “Query DOM for bookmarked tweets”
- “Click ‘remove bookmark’ button”
- “Scroll to load more”
- “Detect end-of-list / no more bookmarks”

##### Content Script → Popup UI (via messaging)
- Progress updates: `{removedCount, remainingEstimate, status}`
- Errors/retries: `{errorType, retryCount}`
- Completion: `{done: true}`

- “Unbookmark API requests triggered by DOM click”
- “Fetch next page of bookmarks triggered by scroll”

##### Architectural patterns used
- **Browser extension “UI + injected automation” pattern**
- **Event/message-driven coordination** (popup commands; content emits progress)
- **DOM automation / RPA-like behavior** (operates by interacting with the web UI)
- **Client-only / privacy-by-design** (explicit “no external servers”)

##### Technologies that matter
- “Chrome Extension (Manifest V3 or V2—confirm from `manifest.json`)”
- “Content Script (JavaScript injected into x.com)”
- “Popup (HTML/CSS/JS)”
- “Chrome Runtime Messaging API”
- “X.com Bookmarks page DOM”

Before finalizing, quickly open `manifest.json` and verify:
- Manifest version (MV3 vs MV2)
- `content_scripts.matches` scope (x.com only? bookmarks path?)
- Permissions (tabs, scripting, activeTab, storage, etc.)
- Whether there is a background service worker (not shown in tree, but manifest confirms)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Diagram 1: Runtime Architecture
    %% =========================
    subgraph "Runtime Architecture (Client-only in Browser)"
        direction TB

        U["User"]:::external

        subgraph "Chrome Extension (Trusted code)"
            direction TB

            M["Extension Manifest\n(wiring,permissions,host_matches)"]:::manifest

            subgraph "Popup UI (Ephemeral controller/dashboard)"
                direction TB
                PH["popup.html\n(UI layout)"]:::frontend
                PJ["popup.js\n(controller + messaging)"]:::frontend
                PC["popup.css\n(styling)"]:::frontend
            end

            CS["Content Script: Bookmark Cleaner\n(DOM automation loop)"]:::worker

            A["Assets\n(icons/images)"]:::assets
        end

        subgraph "Chrome / Extension Runtime APIs (Privileged boundary)"
            direction TB
            RM["chrome.runtime messaging\n(Popup ↔ Content Script)"]:::chromeapi
            CT["chrome.tabs / scripting\n(select_tab,ensure_injection)"]:::chromeapi
        end

        subgraph "X (Twitter) Website (3rd-party page context)"
            direction TB
            XD["Bookmarks Page DOM\nhttps://x.com/i/bookmarks\n(infinite_scroll + bookmark_buttons)"]:::web
            XB["X Backend/API\n(implicit network effects)"]:::externalDashed
        end

        %% --- User interactions
        U -->|"open_extension_popup"| PH
        U -->|"set_delay_ms"| PJ
        U -->|"click_start/stop"| PJ

        %% --- Manifest wiring (conceptual)
        M -->|"declares_popup_entrypoint"| PH
        M -->|"declares_content_script_matches"| CS
        M -->|"declares_permissions"| CT

        %% --- Popup to content script commands
        PJ -->|"sendMessage(START{delayMs})"| RM
        PJ -->|"sendMessage(STOP)"| RM
        PJ -->|"sendMessage(SET_DELAY{delayMs})"| RM

        RM -->|"deliver_command"| CS
        CT -->|"get_active_tab/inject_if_needed"| CS

        %% --- Content script DOM automation
        CS -->|"query_DOM_for_bookmarks"| XD
        CS -->|"click_remove_bookmark"| XD
        CS -->|"delay/rate_limit_pacing"| CS
        CS -->|"scroll_to_load_more"| XD
        CS -->|"retry_on_error"| CS
        CS -->|"detect_end_of_list"| XD

        %% --- Progress back to popup
        CS -->|"emit_progress({removedCount,status,errors})"| RM
        RM -->|"update_UI(progress/errors/done)"| PJ
        PJ -->|"render_progress"| PH

        %% --- Indirect network effects (optional)
        XD -.->|"unbookmark_requests_triggered_by_clicks"| XB
        XD -.->|"fetch_more_on_scroll"| XB

        %% --- Notes
        N1["No backend service\nNo external data store\nAll processing local in browser"]:::note
        CS -->|"privacy_by_design"| N1
    end

    %% =========================
    %% Diagram 2: Release / Packaging Pipeline
    %% =========================
    subgraph "Release / Packaging Pipeline (Repo → Artifact)"
        direction TB

        DEV["Developer"]:::external
        REPO["Git Repository"]:::repo
        PKG["package.json\n(tooling/metadata)"]:::cicd
        VU["update-version.js\n(bump_version)"]:::cicd
        GA["GitHub Actions\nrelease.yml"]:::cicd
        ART["Release Artifact\n(zipped extension)"]:::artifact
        INSTALL["User installs in Chrome\nchrome://extensions → Load unpacked\n(or unzip + load)"]:::external

        DEV -->|"commit_changes"| REPO
        PKG -->|"defines_version/scripts"| VU
        REPO -->|"run_version_bump"| VU
        REPO -->|"push/tag"| GA
        VU -->|"update_version_in_repo"| REPO
        GA -->|"build/package"| ART
        ART -->|"download"| INSTALL
    end

    %% =========================
    %% Click Events (from mapping)
    %% =========================
    click M "https://github.com/ahmed-abdelwahed1/x-unbookmarker/blob/main/manifest.json"
    click PH "https://github.com/ahmed-abdelwahed1/x-unbookmarker/blob/main/src/popup.html"
    click PJ "https://github.com/ahmed-abdelwahed1/x-unbookmarker/blob/main/src/popup.js"
    click PC "https://github.com/ahmed-abdelwahed1/x-unbookmarker/blob/main/src/popup.css"
    click CS "https://github.com/ahmed-abdelwahed1/x-unbookmarker/blob/main/src/content.js"
    click A "https://github.com/ahmed-abdelwahed1/x-unbookmarker/tree/main/assets/"
    click GA "https://github.com/ahmed-abdelwahed1/x-unbookmarker/blob/main/.github/workflows/release.yml"
    click VU "https://github.com/ahmed-abdelwahed1/x-unbookmarker/blob/main/update-version.js"
    click PKG "https://github.com/ahmed-abdelwahed1/x-unbookmarker/blob/main/package.json"

    %% =========================
    %% Styles
    %% =========================
    classDef frontend fill:#1976d2,stroke:#0d47a1,color:#ffffff,stroke-width:1.5px
    classDef worker fill:#1565c0,stroke:#0d47a1,color:#ffffff,stroke-width:1.5px
    classDef manifest fill:#1e88e5,stroke:#0d47a1,color:#ffffff,stroke-width:1.5px
    classDef assets fill:#42a5f5,stroke:#0d47a1,color:#0b1b2b,stroke-width:1.5px

    classDef chromeapi fill:#9e9e9e,stroke:#424242,color:#111111,stroke-width:1.5px

    classDef web fill:#ffffff,stroke:#111111,color:#111111,stroke-width:1.5px
    classDef external fill:#f5f5f5,stroke:#616161,color:#111111,stroke-width:1.5px
    classDef externalDashed fill:#fafafa,stroke:#616161,color:#111111,stroke-width:1.5px,stroke-dasharray: 6 4

    classDef note fill:#fff8e1,stroke:#f9a825,color:#4e3b00,stroke-width:1.5px

    classDef cicd fill:#7b1fa2,stroke:#4a148c,color:#ffffff,stroke-width:1.5px
    classDef repo fill:#6a1b9a,stroke:#4a148c,color:#ffffff,stroke-width:1.5px
    classDef artifact fill:#ad1457,stroke:#880e4f,color:#ffffff,stroke-width:1.5px
```
