# zjingwen/v-jstools architecture

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

- Interactive diagram: https://gitdiagram.com/zjingwen/v-jstools
- Repository: https://github.com/zjingwen/v-jstools

## Overview

##### Project Type and Purpose
- The project is a browser extension (an upgraded version to support Manifest V3) built for development and possibly code debugging and manipulation.
- The README hints that this version focuses on supporting Manifest V3 (with legacy Manifest V2 support dropped) and includes new build processes via Vite. It is also meant for educational and reference purposes.
- The project includes several HTML pages (e.g., for popup, options, devtools, background) and multiple JavaScript files that operate as the logic for these pages.

##### Analysis of the File Structure
- At the root, there are key files like manifest.json and package.json. The manifest defines extension permissions, scripts, and page associations, which is critical to the architecture.
- HTML and JS files such as popup.html/popup.js, options.html/options.js, devtools.html/devtools.js, background.html/background.js, and new_tab_overwrite.html indicate different UI entry points within the extension.
- The lib folder contains helper and utility libraries (e.g., code_hookdom.js, my_magic_obj.js) which support core functionalities.
- The tools folder is sizable and further decomposes into various scripts performing functionalities like AST parsing (astexplorer_babel.js), diffing (diff_text.js), code obfuscation (js_obfuscator.js), encryption (jsencrypt.js), and other tasks divided into subfolders (for example, the bgscript folder for background script utilities).
- The presence of configuration files and build scripts like the vite configuration (mentioned in README) indicates a build process for bundling the extension.

a. Main Components to Represent:
- Manifest and Build Pipeline: Start with manifest.json as the entry point and include the build process (via Vite) that compiles and bundles the extension files.
- Extension Pages:
▪ Popup Interface: popup.html and its associated JavaScript.
▪ Options Page: options.html and options.js for user settings.
▪ New Tab Overwrite: new_tab_overwrite.html, potentially replacing the browser’s new tab.
▪ DevTools Panel: devtools.html and devtools.js that extend browser developer tools.
▪ Background Script: background.html and background.js acting as the service worker/background process.
▪ Content Scripts: inject.js (and possibly others) that gets injected into pages as needed.
- Utility Libraries and Tools:
▪ The lib folder containing general-purpose libraries.
▪ The tools folder with specialized helper scripts broken into categories (AST processing, encryption/obfuscation, diffing functions, etc.).
- Additional Assets: Files like astexplorer_babel.html or background.html which might be used for debugging or interactive demos.

b. Relationships and Interactions:
- The manifest defines which scripts/pages run in what context. Capture directional flows:
▪ The background process communicates with the popup, options, and devtools panels as needed.
▪ Content scripts (e.g., inject.js) interact with web pages, and they might use functions from the tools and lib folders.
▪ Utility modules under tools can be invoked by multiple UI components and by the background script for operations like code transformation, encryption, or diff computations.
- The Vite build process takes the source files (including files in tools and lib) and bundles them for deployment, ensuring the Manifest V3 compliance.

c. Architectural Patterns and Design Principles:
- The design follows a modular structure with separation of concerns:
▪ Different HTML pages and JS files handle specific functionalities.
▪ Utility libraries are segregated in lib/ and tools/ directories.
- There’s an inherent component-based architecture imposed by the extension’s multiple views that interact with a common background process.

d. Technologies and Frameworks:
- Browser Extension Manifest V3 specifics (as outlined in manifest.json).
- Vite build tooling (as added in the update log).
- Various JavaScript modules for AST processing (e.g., astexplorer_babel.js), code obfuscation (e.g., js_obfuscator.js), encryption (e.g., jsencrypt.js), and other code manipulations.

##### Specific Elements
- Use clear and descriptive labels for each component:
▪ "Manifest (manifest.json)"
▪ "Background Process (background.js / background.html)"
▪ "Popup UI (popup.html/popup.js)"
▪ "Options UI (options.html/options.js)"
▪ "DevTools Panel (devtools.html/devtools.js)"
▪ "Content Scripts (inject.js)"
▪ "Utility Libraries (lib folder)"
▪ "Specialized Tools (tools folder including bgscript, AST tools, diffing, obfuscation, etc.)"
▪ From manifest to each UI component and background script.
▪ Between UI components and the background process.
▪ From background script to utility modules (tools and lib).
▪ For the Vite build process, show the transformation from source files to bundled outputs.
- Differentiate components:

##### Final Reminder
- Avoid over-simplification – prioritize capturing every essential module from the file tree, as this separation of components will aid in both understanding and further development or debugging.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Build
    subgraph "Configuration & Build"
        Manifest["Manifest (manifest.json)"]:::config
        Package["Package File (package.json)"]:::config
        Vite["Build Process (Vite)"]:::build
    end

    %% Extension UI
    subgraph "Extension UI"
        subgraph "Popup UI"
            PopupHTML["Popup HTML"]:::ui
            PopupJS["Popup JS"]:::ui
        end
        subgraph "Options UI"
            OptionsHTML["Options HTML"]:::ui
            OptionsJS["Options JS"]:::ui
        end
        subgraph "DevTools Panel"
            DevToolsHTML["DevTools HTML"]:::ui
            DevToolsJS["DevTools JS"]:::ui
        end
        NewTab["New Tab Overwrite"]:::ui
    end

    %% Background & Content Scripts
    subgraph "Background & Content Scripts"
        subgraph "Background Process"
            BackgroundHTML["Background HTML"]:::background
            BackgroundJS["Background JS"]:::background
        end
        ContentScript["Content Script (inject.js)"]:::background
    end

    %% Utility Modules
    subgraph "Utility Modules"
        Lib["Utility Libraries"]:::utility
        subgraph "Specialized Tools"
            ToolsOverall["Tools"]:::utility
            BGScript["BGScript Tools"]:::utility
        end
    end

    %% Connections from Configuration to Build Process
    Manifest -->|"configures"| Vite
    Package -->|"configures"| Vite

    %% Build Process bundles source files from Utility Modules
    Lib -->|"bundled"| Vite
    ToolsOverall -->|"bundled"| Vite

    %% Vite delivers bundle to Extension components
    Vite -->|"bundle-delivers"| PopupHTML
    Vite -->|"bundle-delivers"| OptionsHTML
    Vite -->|"bundle-delivers"| NewTab
    Vite -->|"bundle-delivers"| DevToolsHTML
    Vite -->|"bundle-delivers"| BackgroundHTML
    Vite -->|"bundle-delivers"| ContentScript

    %% Manifest defines the extension components
    Manifest -->|"defines"| PopupHTML
    Manifest -->|"defines"| OptionsHTML
    Manifest -->|"defines"| NewTab
    Manifest -->|"defines"| DevToolsHTML
    Manifest -->|"defines"| BackgroundHTML
    Manifest -->|"defines"| ContentScript

    %% Communication between UI components and Background Process
    PopupJS -->|"communicates"| BackgroundHTML
    OptionsJS -->|"communicates"| BackgroundHTML
    DevToolsJS -->|"communicates"| BackgroundHTML

    %% Background and Content usage of Utility Modules
    BackgroundJS -->|"utilizes"| Lib
    BackgroundJS -->|"utilizes"| ToolsOverall
    ContentScript -->|"utilizes"| Lib
    ContentScript -->|"utilizes"| ToolsOverall

    %% Tools contains BGScript modules
    ToolsOverall -->|"includes"| BGScript

    %% Class definitions for styling
    classDef config fill:#ffedad,stroke:#333,stroke-width:2px;
    classDef build fill:#ffe6e6,stroke:#333,stroke-width:2px;
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef background fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef utility fill:#fffacd,stroke:#333,stroke-width:2px;

    %% Click Events
    click Manifest "https://github.com/zjingwen/v-jstools/blob/main/manifest.json"
    click Package "https://github.com/zjingwen/v-jstools/blob/main/package.json"
    click PopupHTML "https://github.com/zjingwen/v-jstools/blob/main/popup.html"
    click PopupJS "https://github.com/zjingwen/v-jstools/blob/main/popup.js"
    click OptionsHTML "https://github.com/zjingwen/v-jstools/blob/main/options.html"
    click OptionsJS "https://github.com/zjingwen/v-jstools/blob/main/options.js"
    click NewTab "https://github.com/zjingwen/v-jstools/blob/main/new_tab_overwrite.html"
    click DevToolsHTML "https://github.com/zjingwen/v-jstools/blob/main/devtools.html"
    click DevToolsJS "https://github.com/zjingwen/v-jstools/blob/main/devtools.js"
    click BackgroundHTML "https://github.com/zjingwen/v-jstools/blob/main/background.html"
    click BackgroundJS "https://github.com/zjingwen/v-jstools/blob/main/background.js"
    click ContentScript "https://github.com/zjingwen/v-jstools/blob/main/inject.js"
    click Lib "https://github.com/zjingwen/v-jstools/tree/main/lib/"
    click ToolsOverall "https://github.com/zjingwen/v-jstools/tree/main/tools/"
    click BGScript "https://github.com/zjingwen/v-jstools/tree/main/tools/bgscript/"
```
