# ophilar/tabtogether architecture

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

- Interactive diagram: https://gitdiagram.com/ophilar/tabtogether
- Repository: https://github.com/ophilar/tabtogether

## Overview

##### Project type and purpose
- TabTogether is a browser extension (Firefox Add-on) whose purpose is to let users define device “groups” and seamlessly send tabs between all members of a group by leveraging the Firefox Sync service.

##### Main architectural components
a. Browser Extension Container
- Popup UI (popup.html + popup.js + popup.css)
- Options UI (options.html + options.js + shared-ui.js + styles.css)
- Context-menu handler (registered in background.js)
- Background script (background.js + constants.js + utils.js + theme.js)
- Local storage module (browser.storage.local)
- Sync storage module (browser.storage.sync)
- Notification module (browser.notifications)
- Tests (jest + integration.test.js + utils.test.js)
b. External Service
- Firefox Sync (cloud-hosted key/value store and pub/sub mechanism for extension data)

##### Component relationships and data flow
- UI → Background
- popup.js and options.js send messages (browser.runtime.sendMessage) to background.js
- Background → Storage
- background.js writes group definitions and device subscriptions to browser.storage.local
- background.js writes “tab send” events into browser.storage.sync for distribution
- Firefox Sync → Background (on other devices)
- Storage.sync.onChanged events fire in background.js on all subscriber devices
- background.js responds by opening the incoming tab via browser.tabs.create
- Background → Notifications
- background.js uses browser.notifications to alert user of success or errors
- Context Menu → Background
- background.js registers a right-click menu (browser.contextMenus.create) and handles clicks to trigger the same “send tab” flow

##### Architectural patterns and design principles
- Event-driven messaging (UI ↔ background via runtime messages)
- Pub/Sub via storage.sync (leverages Firefox Sync as a distributed event bus)
- Separation of concerns:
- UI layer (popup/options)
- Orchestration layer (background)
- Persistence layer (local vs. sync storage)
- Reusable utilities (constants.js, utils.js) shared between background and UI

##### Detail and clarity
- Distinguish local vs. sync storage.
- Both UI-initiated flows (popup/options/context menu) and incoming flows from Sync.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Extension Boundary
    subgraph "Browser Extension"
        %% UI Layer
        subgraph "UI Layer" 
            direction TB
            PopupHTML["popup.html"]:::ui
            PopupJS["popup.js"]:::ui
            PopupCSS["popup.css"]:::ui
            OptionsHTML["options.html"]:::ui
            OptionsJS["options.js"]:::ui
            SharedUIJS["shared-ui.js"]:::ui
            SharedUICSS["shared-ui.css"]:::ui
            StylesCSS["styles.css"]:::ui
        end

        %% Orchestration Layer
        subgraph "Background Layer"
            direction TB
            BackgroundJS["background.js"]:::orchestr
            ConstantsJS["constants.js"]:::orchestr
            UtilsJS["utils.js"]:::orchestr
            ThemeJS["theme.js"]:::orchestr
            ContextMenu["Context-Menu Handler"]:::misc
        end

        %% Storage Layer
        subgraph "Storage Layer"
            direction TB
            LocalStorage[(Local Storage)]:::storage
            SyncStorage[(Sync Storage)]:::storage
        end
    end

    %% External Services and APIs
    FirefoxSync["Firefox Sync"]:::external
    TabsAPI["Tabs API"]:::external
    NotificationsAPI["Notifications API"]:::misc
    ContextMenuListener["contextMenus.onClicked"]:::misc

    %% Test Suite
    TestSuite["Jest Test Suite"]:::misc
    IntegrationTest["integration.test.js"]:::misc
    UtilsTest["utils.test.js"]:::misc
    SetupTest["setup.js"]:::misc

    %% Flows: UI to Background
    PopupJS -->|"runtime.sendMessage"| BackgroundJS
    OptionsJS -->|"runtime.sendMessage"| BackgroundJS

    %% Context Menu to Background
    ContextMenuListener -->|"contextMenus.onClicked"| BackgroundJS

    %% Background to Storage
    BackgroundJS -->|"storage.local.set/get"| LocalStorage
    BackgroundJS -->|"storage.sync.set(tabEvent)"| SyncStorage

    %% Sync replication
    FirefoxSync -->|"automatic replication"| SyncStorage
    SyncStorage -->|"storage.onChanged"| BackgroundJS

    %% Background to Tabs & Notifications
    BackgroundJS -->|"tabs.create(…)"| TabsAPI
    BackgroundJS -->|"notifications.create"| NotificationsAPI

    %% Tests coverage
    TestSuite --> IntegrationTest
    TestSuite --> UtilsTest
    TestSuite --> SetupTest
    IntegrationTest --> BackgroundJS
    UtilsTest --> UtilsJS

    %% Click events for component mapping
    click PopupHTML "https://github.com/ophilar/tabtogether/blob/main/popup.html"
    click PopupJS "https://github.com/ophilar/tabtogether/blob/main/popup.js"
    click PopupCSS "https://github.com/ophilar/tabtogether/blob/main/popup.css"
    click OptionsHTML "https://github.com/ophilar/tabtogether/blob/main/options.html"
    click OptionsJS "https://github.com/ophilar/tabtogether/blob/main/options.js"
    click SharedUIJS "https://github.com/ophilar/tabtogether/blob/main/shared-ui.js"
    click SharedUICSS "https://github.com/ophilar/tabtogether/blob/main/shared-ui.css"
    click StylesCSS "https://github.com/ophilar/tabtogether/blob/main/styles.css"
    click BackgroundJS "https://github.com/ophilar/tabtogether/blob/main/background.js"
    click ConstantsJS "https://github.com/ophilar/tabtogether/blob/main/constants.js"
    click UtilsJS "https://github.com/ophilar/tabtogether/blob/main/utils.js"
    click ThemeJS "https://github.com/ophilar/tabtogether/blob/main/theme.js"
    click TestSuite "https://github.com/ophilar/tabtogether/blob/main/jest.config.cjs"
    click IntegrationTest "https://github.com/ophilar/tabtogether/blob/main/test/integration.test.js"
    click UtilsTest "https://github.com/ophilar/tabtogether/blob/main/test/utils.test.js"
    click SetupTest "https://github.com/ophilar/tabtogether/blob/main/test/setup.js"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#000,stroke-width:1px
    classDef orchestr fill:#D0FFD0,stroke:#000,stroke-width:1px
    classDef storage fill:#FFE0B2,stroke:#000,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#000,stroke-width:1px
    classDef misc fill:#E1BEE7,stroke:#000,stroke-width:1px
```
