# toby-wong/buywisely-firefox architecture

> Architecture diagram of the GitHub repository toby-wong/buywisely-firefox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/toby-wong/buywisely-firefox
- Repository: https://github.com/toby-wong/buywisely-firefox

## Overview

##### Project type and purpose
- This is a browser extension (specifically the Firefox port of a Chrome extension) called “buywisely-firefox.”
- Its purpose is to compare and track product prices on e-commerce sites by injecting scripts into web pages, communicating with background logic, and optionally calling external services for data.

##### File structure
- Top-level files:
- manifest.json – defines extension metadata, permissions, scripts, and entry points.
- background.js – the background service worker or event page, responsible for long-lived tasks and centralized logic.
- content.js – the content script injected into matching web pages to scrape DOM data or augment the UI.
- content.js.LICENSE.txt – licensing for the content script.
- metadata.json and the _metadata folder – auto-generated by web-ext for packaging and verification.
- web-ext-artifacts – packaged output (XPI and ZIP) ready for release.

##### README for additional insights
- Confirms this is purely a client-side extension, installed via about:addons.
- No backend server code in the repo, so all functionality lives within the browser environment.

##### Be detailed and capture essential elements
- Permissions (e.g., “<all_urls>” or storage) listed in manifest.json.
- Packaging artifacts folder as part of the CI/CD or release pipeline.
- Version number (0.0.1) and where it appears in manifest.json and metadata.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Browser Environment
    Browser["Firefox Browser"]:::browser

    %% WebExtensions Core
    subgraph "WebExtensions Core"
        Manifest["manifest.json"]:::core
        Background["background.js"]:::core
        Content["content.js"]:::core
        License["content.js.LICENSE.txt"]:::core
    end

    %% Browser APIs
    subgraph "Browser APIs"
        Storage["browser.storage API"]:::browser
    end

    %% External Services & Build Tools
    subgraph "External Services & Build Tools"
        ExternalAPI["External Price-History API"]:::external
        Build["web-ext Build Pipeline"]:::external
        Artifacts["web-ext-artifacts/"]:::external
        MetadataJSON["metadata.json"]:::external
        MetadataDir["_metadata/"]:::external
        Readme["README.md"]:::external
    end

    %% Relationships
    Browser --> Manifest
    Manifest --> Content
    Manifest --> Background
    Content <--> Background
    Background --> Storage
    Background --> ExternalAPI
    Build --> Manifest
    Build --> Content
    Build --> Background
    Build --> Artifacts
    Build --> MetadataJSON
    Build --> MetadataDir
    Build --> Readme
    Artifacts --> Browser

    %% Click Events
    click Manifest "https://github.com/toby-wong/buywisely-firefox/blob/main/manifest.json"
    click Background "https://github.com/toby-wong/buywisely-firefox/blob/main/background.js"
    click Content "https://github.com/toby-wong/buywisely-firefox/blob/main/content.js"
    click License "https://github.com/toby-wong/buywisely-firefox/blob/main/content.js.LICENSE.txt"
    click MetadataJSON "https://github.com/toby-wong/buywisely-firefox/blob/main/metadata.json"
    click MetadataDir "https://github.com/toby-wong/buywisely-firefox/tree/main/_metadata/"
    click Artifacts "https://github.com/toby-wong/buywisely-firefox/tree/main/web-ext-artifacts/"
    click Readme "https://github.com/toby-wong/buywisely-firefox/blob/main/README.md"

    %% Styles
    classDef core fill:#AED6F1,stroke:#21618C,color:#1B2631;
    classDef browser fill:#ABEBC6,stroke:#1D8348,color:#1B2631;
    classDef external fill:#F5CBA7,stroke:#BA4A00,color:#1B2631;
```
