# googlechromelabs/projectvisbug architecture

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

- Interactive diagram: https://gitdiagram.com/googlechromelabs/projectvisbug
- Repository: https://github.com/googlechromelabs/projectvisbug

## Overview

##### Project type and purpose
- This is an **open-source browser extension** (VisBug) plus accompanying **demo/static site**, with a **Safari desktop extension** packaged in an Xcode project.
- Purpose: Provide in-page web design/debug tooling by injecting UI elements/components into any website at runtime.

##### File structure
- Top level:
- `.github/workflows` → CI (build & test pipelines)
- `VisBug/VisBug Extension` & `VisBug.xcodeproj` → Safari extension mac app
- `extension/` → Chrome/Edge/Firefox extension source & manifest
- `app/` → Demo site, built docs, feature‐driven modules, utilities, components, plugins
- `assets/` → static assets (images, Sketch files)
- `rollup.config.mjs`, `package.json` → bundler config & npm scripts
- `firebase.json`, `app.yaml`, `.firebaserc` → hosting/deploy config
- Patterns:
- Modular feature architecture (`app/features`, `app/components`, `app/plugins`)
- Web Components (custom elements, CSS modules)
- Bundled outputs for extension vs demo site

##### README for additional insights
- Core design/debug tool
- Built to “point, click & tinker” with site DOM
- Supports multiple browsers (Chrome, Firefox, Safari, Edge)
- Uses Chrome-extension manifest + browser APIs
- Demo site hosted on Firebase/GCP

##### Essential detail checklist
- **build steps** separately from **runtime flow**
- **multi-browser** packaging
- **Web Component registry** and **dynamic injection** mechanism
- **CI tests** and **deployment** to stores/hosts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source
    Dev["Developer Workstation / Source Repo"]:::dev
    Dev -->|push to repo| CI

    %% CI/CD
    CI["CI/CD (GitHub Actions)"]:::build
    click CI "https://github.com/googlechromelabs/projectvisbug/blob/main/.github/workflows/main.yml"
    click CI "https://github.com/googlechromelabs/projectvisbug/blob/main/.github/workflows/test.yml"
    CI -->|runs tests & builds| Rollup
    CI -->|runs tests & builds| Npm

    %% Build Tools
    subgraph "Build Tools"
        Rollup["Rollup (rollup.config.mjs)"]:::build
        click Rollup "https://github.com/googlechromelabs/projectvisbug/blob/main/rollup.config.mjs"
        Npm["npm scripts (package.json)"]:::build
        click Npm "https://github.com/googlechromelabs/projectvisbug/blob/main/package.json"
    end
    Rollup -->|bundle| ExtBundle
    Npm -->|bundle| ExtBundle
    Rollup -->|bundle| DemoBundle
    Npm -->|bundle| DemoBundle

    %% Artifacts
    ExtBundle["Extension Bundles"]:::build
    DemoBundle["Demo Site Artifacts"]:::build

    %% Publish / Hosting
    subgraph "Publish / Hosting" 
        Firebase["Firebase Hosting"]:::publish
        click Firebase "https://github.com/googlechromelabs/projectvisbug/blob/main/firebase.json"
        click Firebase "https://github.com/googlechromelabs/projectvisbug/blob/main/.firebaserc"
        click Firebase "https://github.com/googlechromelabs/projectvisbug/blob/main/app.yaml"
        ChromeStore["Chrome Web Store"]:::publish
        FirefoxStore["Firefox Add-ons"]:::publish
        SafariAppStore["Safari App Store"]:::publish
    end
    ExtBundle -->|upload| ChromeStore
    ExtBundle -->|upload| FirefoxStore
    ExtBundle -->|package & upload| SafariAppStore
    DemoBundle -->|deploy via firebase CLI| Firebase

    %% Runtime Environments
    subgraph "Runtime Environments"
        subgraph "Browser Extension" 
            BManifest["manifest.json"]:::runtime
            click BManifest "https://github.com/googlechromelabs/projectvisbug/blob/main/extension/manifest.json"
            BCore["visbug.js"]:::runtime
            click BCore "https://github.com/googlechromelabs/projectvisbug/blob/main/extension/visbug.js"
            Context["Context Menu Scripts"]:::runtime
            click Context "https://github.com/googlechromelabs/projectvisbug/tree/main/extension/contextmenu/"
            Toolbar["Toolbar Scripts"]:::runtime
            click Toolbar "https://github.com/googlechromelabs/projectvisbug/tree/main/extension/toolbar/"
        end
        subgraph "Safari Desktop Extension"
            XcodeProj["VisBug.xcodeproj"]:::runtime
            click XcodeProj "https://github.com/googlechromelabs/projectvisbug/blob/main/VisBug/VisBug.xcodeproj"
            SDir["VisBug Extension Dir"]:::runtime
            click SDir "https://github.com/googlechromelabs/projectvisbug/tree/main/VisBug/VisBug Extension"
            InfoPlist["Info.plist"]:::runtime
            click InfoPlist "https://github.com/googlechromelabs/projectvisbug/blob/main/VisBug/VisBug Extension/Info.plist"
            Handler["SafariWebExtensionHandler.swift"]:::runtime
            click Handler "https://github.com/googlechromelabs/projectvisbug/blob/main/VisBug/VisBug Extension/SafariWebExtensionHandler.swift"
        end
        subgraph "Demo / Static Website"
            IndexHTML["index.html"]:::runtime
            click IndexHTML "https://github.com/googlechromelabs/projectvisbug/blob/main/app/index.html"
            IndexJS["index.js"]:::runtime
            click IndexJS "https://github.com/googlechromelabs/projectvisbug/blob/main/app/index.js"
            IndexCSS["index.css"]:::runtime
            click IndexCSS "https://github.com/googlechromelabs/projectvisbug/blob/main/app/index.css"
            DemoCSS["demo styles"]:::runtime
            click DemoCSS "https://github.com/googlechromelabs/projectvisbug/tree/main/app/demo/"
            Assets["static assets"]:::runtime
            click Assets "https://github.com/googlechromelabs/projectvisbug/tree/main/app/assets"
        end
    end

    %% Injection Engine Modules
    subgraph "Injection Engine (Core Modules)"
        Features["Core Feature Modules"]:::modules
        click Features "https://github.com/googlechromelabs/projectvisbug/tree/main/app/features/"
        Components["Web Components Library"]:::modules
        click Components "https://github.com/googlechromelabs/projectvisbug/tree/main/app/components/"
        Plugins["Plugin System"]:::modules
        click Plugins "https://github.com/googlechromelabs/projectvisbug/blob/main/app/plugins/_registry.js"
        click Plugins "https://github.com/googlechromelabs/projectvisbug/blob/main/app/plugins/_dynamic-registery.js"
        Utilities["Utilities (shared helpers)"]:::modules
        click Utilities "https://github.com/googlechromelabs/projectvisbug/tree/main/app/utilities/"
        CSS["Extension Styling"]:::modules
        click CSS "https://github.com/googlechromelabs/projectvisbug/blob/main/app/extension.css"
    end

    %% Runtime flow
    Browser_Ext -->|loads bundle| Features
    Safari_Ext -->|loads bundle| Features
    DemoBundle -->|serves static| IndexHTML
    Features --> Components
    Features --> Plugins
    Features --> Utilities
    Components --> Plugins
    Plugins --> Utilities
    Features --> CSS

    %% User Interaction
    EndUser["End User"]:::runtime
    Browser_Ext -->|installs| EndUser
    Safari_Ext -->|installs| EndUser
    EndUser -->|browses site| DemoBundle
    EndUser -->|interacts with UI| Browser_Ext
    EndUser -->|interacts with UI| Safari_Ext

    %% Styles
    classDef dev fill:#D6EAF8,stroke:#2980B9,color:#154360
    classDef build fill:#AED6F1,stroke:#1A5276,color:#1B4F72
    classDef publish fill:#ABEBC6,stroke:#239B56,color:#145A32
    classDef runtime fill:#F9E79F,stroke:#B9770E,color:#7E5109
    classDef modules fill:#E8DAEF,stroke:#76448A,color:#512E5F

    %% Aliases for arrows
    Browser_Ext(Browser Extension)
    Safari_Ext(Safari Desktop Extension)
```
