# vibinex/chrome-extension architecture

> Architecture diagram of the GitHub repository vibinex/chrome-extension, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vibinex/chrome-extension
- Repository: https://github.com/vibinex/chrome-extension

## Overview

##### Project type and purpose
- This is a browser extension (Chrome) that enhances code reviews on GitHub and Bitbucket by injecting personalized highlighting into the PR UI.
- Key purpose: intercept DOM in PR pages, compute/apply highlights based on user preferences, offer a popup UI for settings/triggers.

##### File structure
- manifest.json: declares extension metadata, permissions, content scripts, background scripts, popup.
- backgroundScript.js: persistent background page that listens for messages, manages state, possibly triggers API calls.
- popup/ (popup.html, popup.js, popup_css.css): UI layer for user interactions (initialization, settings, manual triggers).
- scripts/ : content scripts injected into GitHub/Bitbucket pages:
- init.js – detects the PR page and bootstraps orchestration
- orchestrator.js – central coordinator for incoming events (page load, user actions)
- api.js – communicates with external Vibinex services or local storage for user preferences
- highlighting.js – applies CSS classes or inline styles to code diffs
- repoHandlers.js – platform-specific logic for GitHub vs Bitbucket DOM structures
- triggerButton.js – inserts UI controls into the page
- signedOutIndicator.js – displays state if user isn’t logged in
- utilities.js, main.css – shared helper functions and styling

##### README for additional insights
- Technologies: pure JavaScript, Chrome Extension APIs, DOM manipulation, optional remote API.

##### Components & Interactions
a. Main components
- Browser (Chrome)
- Extension manifest (registration)
- Background script (backgroundScript.js)
- Content scripts (init.js, orchestrator.js, repoHandlers.js, highlighting.js, etc.)
- Popup UI (popup.html/js)
- External Vibinex API or storage (optional remote service)
- Target web pages (GitHub PR, Bitbucket PR)

b. Relationships & data flow
1. Browser loads the extension via manifest.json
2. On page navigation to a PR: content scripts are injected
3. init.js detects PR URLs and notifies orchestrator.js
4. orchestrator.js requests user preferences via api.js (Chrome.storage or remote API through background script)
5. api.js (in content or via message to backgroundScript.js) fetches config
6. orchestrator.js calls repoHandlers.js to map DOM elements
7. highlighting.js applies CSS/styling to code diffs
8. triggerButton.js optionally adds manual trigger controls
9. User opens popup → popup.js communicates with backgroundScript.js → may update preferences
10. backgroundScript.js persists settings to Chrome.storage or relays to remote API

c. Architectural patterns / design principles
- Event-driven: relies on Chrome runtime messaging and DOM events
- Separation of concerns:
- Manifest defines “what” to inject / run
- Background script handles persistent state, cross-origin API calls
- Content scripts handle DOM detection & manipulation
- Popup UI is isolated web UI communicating via messages
- Platform adapters (repoHandlers.js) abstract GitHub vs Bitbucket differences

d. Relevant technologies / frameworks
- Chrome Extension APIs (runtime, storage, tabs)
- Vanilla JavaScript and CSS
- External REST API (if user preferences are stored remotely)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Container
    subgraph "Browser (Chrome)"
        direction TB

        %% Extension Container
        subgraph "Extension"
            direction TB

            Manifest["Manifest (manifest.json)"]:::manifest
            Background["Background Script"]:::background
            subgraph "Popup UI"
                direction TB
                PopupHTML["popup.html"]:::popup
                PopupJS["popup.js"]:::popup
                PopupCSS["popup_css.css"]:::popup
            end

            subgraph "Content Scripts"
                direction TB
                Init["init.js"]:::content
                Orchestrator["orchestrator.js"]:::content
                API["api.js"]:::content
                Highlight["highlighting.js"]:::content
                MainCSS["main.css"]:::content
                RepoHandlers["repoHandlers.js"]:::content
                TriggerBtn["triggerButton.js"]:::content
                SignedOut["signedOutIndicator.js"]:::content
                Utils["utilities.js"]:::content
            end
        end

        %% Target Pages Container
        subgraph "Target Pages"
            direction TB
            GH["GitHub PR Page"]:::page
            BB["Bitbucket PR Page"]:::page
        end
    end

    %% External Service
    External["External Vibinex API"]:::external

    %% Registration Flows
    Manifest -->|"registers"| Background
    Manifest -->|"injects"| Init

    %% Page load & orchestration
    GH -->|"page load"| Init
    BB -->|"page load"| Init
    Init -->|"bootstrap"| Orchestrator
    Orchestrator -->|"getPreferences"| API
    API -->|"chrome.runtime.sendMessage|getPreferences"| Background
    Background -->|"preferences"| API
    API -->|"preferences"| Orchestrator

    %% Highlighting Flow
    Orchestrator -->|"map DOM"| RepoHandlers
    RepoHandlers -->|"DOM elements"| Highlight
    Highlight -->|"applyHighlights"| GH
    Highlight -->|"applyHighlights"| BB

    %% UI Controls on Page
    Orchestrator -->|"insert UI"| TriggerBtn
    Orchestrator -->|"show signed-out"| SignedOut

    %% Popup interactions
    User["User"]:::user
    User -->|"opens popup"| PopupHTML
    PopupHTML -->|"loads"| PopupJS
    PopupJS -->|"updateSettings"| Background
    Background -->|"ack"| PopupJS

    %% Background to External API
    Background -->|"fetchPreferences"| External
    External -->|"preferences"| Background

    %% Click Events
    click Manifest "https://github.com/vibinex/chrome-extension/blob/main/manifest.json"
    click Background "https://github.com/vibinex/chrome-extension/blob/main/backgroundScript.js"
    click PopupHTML "https://github.com/vibinex/chrome-extension/blob/main/popup/popup.html"
    click PopupJS "https://github.com/vibinex/chrome-extension/blob/main/popup/popup.js"
    click PopupCSS "https://github.com/vibinex/chrome-extension/blob/main/popup/popup_css.css"
    click Init "https://github.com/vibinex/chrome-extension/blob/main/scripts/init.js"
    click Orchestrator "https://github.com/vibinex/chrome-extension/blob/main/scripts/orchestrator.js"
    click API "https://github.com/vibinex/chrome-extension/blob/main/scripts/api.js"
    click Highlight "https://github.com/vibinex/chrome-extension/blob/main/scripts/highlighting.js"
    click MainCSS "https://github.com/vibinex/chrome-extension/blob/main/scripts/main.css"
    click RepoHandlers "https://github.com/vibinex/chrome-extension/blob/main/scripts/repoHandlers.js"
    click TriggerBtn "https://github.com/vibinex/chrome-extension/blob/main/scripts/triggerButton.js"
    click SignedOut "https://github.com/vibinex/chrome-extension/blob/main/scripts/signedOutIndicator.js"
    click Utils "https://github.com/vibinex/chrome-extension/blob/main/scripts/utilities.js"
    click External "https://github.com/vibinex/chrome-extension/blob/main/bitbucket-test-trigger.yaml"
    click External "https://github.com/vibinex/chrome-extension/blob/main/ .github/workflows/create-release.yml"

    %% Styles
    classDef manifest fill:#cceeff,stroke:#3399ff
    classDef background fill:#e0f7fa,stroke:#00acc1
    classDef popup fill:#fff9c4,stroke:#fdd835
    classDef content fill:#e8f5e9,stroke:#43a047
    classDef page fill:#ffe0b2,stroke:#fb8c00
    classDef external fill:#eceff1,stroke:#78909c
    classDef user fill:#f3e5f5,stroke:#8e24aa,stroke-dasharray: 5 5,stroke-width:2px
```
