# iitc-ce/iitc-button architecture

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

- Interactive diagram: https://gitdiagram.com/iitc-ce/iitc-button
- Repository: https://github.com/iitc-ce/iitc-button

## Overview

##### Main Components
- Browser Extension Core:
- Background Scripts: Located in “src/background” which handle core background tasks (e.g., network requests, script injection, and utilities).
- Content Scripts: Found in “src/content-scripts” that interact with the webpage, injecting UI or bridging communications.
- Manifest File: “src/manifest.json” defining the extension’s permissions, scripts, and configuration for the browser.
- User Interface (UI) Components:
- Popup UI: Components, views, and supporting data in “src/popup” include Vue components like Alert.vue, Header.vue, and others for the popup interface.
- In-Page/UI Overlays: “src/jsview” (with App.vue, Header.vue, etc.) and “src/settings” housing additional UI components for the settings and advanced features.
- Assets and Localization:
- Public Assets: “public” folder contains static HTML files (e.g., browser-extension.html, index.html), images, and font assets.
- Localization: “public/_locales/…” directory holds translations and locale-specific JSON files.
- Build, Configuration, and Integration:
- Build Files & Scripts: Various npm scripts (build_mv2, build_mv3_firefox, build_mv3_chrome, build_mv3_safari) as defined in package.json, along with Babel, ESLint, and vue.config.js.
- GitHub Workflows: The “.github/workflows” folder shows CI/CD pipelines that build, test, and publish the extension.
- Safari-Specific Implementation:
- Safari: Separate directory with an Xcode project (for both macOS and iOS), shared source files, and pre-build scripts to tailor the extension for Safari environments.

##### Relationships and Interactions
- Data Flow & Communication:
- The background scripts are at the core, managing logic and network communications.
- Content scripts serve as the bridge between the extension and the web page, interacting with the DOM and routing messages to/from background scripts.
- The popup and settings UIs (composed in Vue.js) interact with the background layer through messaging APIs.
- Build & Deployment Flow:
- The project configuration files, along with the npm scripts and GitHub actions, define the build pipelines for various targets (Chrome, Firefox, Safari).
- For Safari, the Xcode project is used to compile and deploy the native-like extension bundle, highlighting platform-specific adjustments.
- Internationalization:
- Localization files (in “public/_locales”) ensure that messages and UI text are available in multiple languages.

##### Architectural Patterns and Design Principles
- Modular Separation:
- Clear separation of concerns: background scripts vs. content scripts vs. UI components.
- Distinct directories for platform-specific code (Safari) and common code.
- MVVM for UI Components:
- Use of Vue.js components suggests a Model-View-ViewModel approach to manage state and view logic in the popup, settings, and in-page elements.
- Build and CI/CD Pipeline:
- The presence of detailed GitHub workflows indicates an automated build, focus on manifest-based differentiations, and continuous integration for quality assurance.
- Localization and Internationalization:
- A dedicated structure for managing file-based translations supports global usage.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "Build & Deployment"
        Config["Build & Config (npm scripts, package.json, babel.config.js, vue.config.js, .eslintrc.js)"]:::build
        CICD["CI/CD Workflows (.github/workflows)"]:::build
    end

    Config -->|"triggers"| Core
    CICD -->|"triggers"| Core

    subgraph "Browser Extension Core"
        Manifest["Manifest File"]:::core
        BS["Background Scripts"]:::core
        CS["Content Scripts"]:::core
    end

    Manifest -->|"loads"| BS
    BS -->|"communicates"| CS

    Intel["Ingress Intel (Official Website)"]:::external
    Intel -->|"data feeds"| CS

    subgraph "User Interface Components"
        Popup_UI["Popup UI (Vue.js)"]:::ui
        JSView["In-Page UI Overlays (jsview)"]:::ui
        Settings_UI["Settings UI (Vue.js)"]:::ui
    end

    BS -->|"messaging"| Popup_UI
    BS -->|"messaging"| JSView
    BS -->|"messaging"| Settings_UI
    CS -->|"injects UI"| JSView

    Assets["Assets & Localization (public)"]:::assets
    Assets -->|"supplies"| Popup_UI
    Assets -->|"supplies"| JSView
    Assets -->|"supplies"| Settings_UI

    Safari["Safari Specific (Xcode Project & Scripts)"]:::safari
    Config -->|"platform build"| Safari

    %% Click Events
    click BS "https://github.com/iitc-ce/iitc-button/tree/master/src/background"
    click CS "https://github.com/iitc-ce/iitc-button/tree/master/src/content-scripts"
    click Manifest "https://github.com/iitc-ce/iitc-button/blob/master/src/manifest.json"
    click Popup_UI "https://github.com/iitc-ce/iitc-button/tree/master/src/popup"
    click JSView "https://github.com/iitc-ce/iitc-button/tree/master/src/jsview"
    click Settings_UI "https://github.com/iitc-ce/iitc-button/tree/master/src/settings"
    click Assets "https://github.com/iitc-ce/iitc-button/tree/master/public"
    click Config "https://github.com/iitc-ce/iitc-button/blob/master/package.json"
    click CICD "https://github.com/iitc-ce/iitc-button/tree/master/.github/workflows"
    click Safari "https://github.com/iitc-ce/iitc-button/tree/master/safari"

    %% Class Definitions for Colors and Styles
    classDef core fill:#f9d1d1,stroke:#333,stroke-width:2px;
    classDef ui fill:#d1f9d1,stroke:#333,stroke-width:2px;
    classDef assets fill:#f9f1d1,stroke:#333,stroke-width:2px;
    classDef build fill:#d1d9f9,stroke:#333,stroke-width:2px;
    classDef safari fill:#f9e1d1,stroke:#333,stroke-width:2px;
    classDef external fill:#d1f9f9,stroke:#333,stroke-width:2px;
    
    %% Grouping Core from Build for vertical layering
    Core --- BS
    Core --- CS
    Core --- Manifest
```
