# hasan-py/ai-assistant-chrome-extension architecture

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

- Interactive diagram: https://gitdiagram.com/hasan-py/ai-assistant-chrome-extension
- Repository: https://github.com/hasan-py/ai-assistant-chrome-extension

## Overview

##### Main Components
- Background Scripts: Found in the “background” directory. Files such as index.js, contextMenuManager.js, and menus.js form a persistent or event-based background process managing global events (e.g., right-click context menus).
- Content Scripts: Located in the “content” directory (content/index.js, content/promptHandler.js, content/promptUi.js) which interact with the current web page. They monitor page content and handle prompts triggered by user actions.
- Manifest and Assets: The manifest.json defines the extension’s behavior and registers scripts. The “asset” directory and any other resources provide static content or styling.

##### Component Relationships and Data Flow
- The manifest.json is the central configuration file that connects all the components by declaring which scripts run in which contexts.
- The background script also sets up context menus using managers defined in background/contextMenuManager.js. When a user right-clicks and selects the specified menu item, the background script triggers the content script.
- The content script (with logic split between promptHandler.js and promptUi.js) then interacts directly with the web page. It processes selected text, shows prompts, or displays results based on actions initiated from either the popup or background.
- The extension may then use the provided API credentials to send requests to external services (like GPT or Gemini) and receive processed text, which is then rendered in the UI.

##### Architectural Patterns & Key Design Principles
- Separation of Concerns: Each major function (UI, background processing, content manipulation) is separated into different directories and scripts.
- Event-Driven Communication: The components communicate via Chrome’s messaging system (e.g., events from the background or content scripts to the popup).
- Modularity: The clear division into popup, background, content, and static assets reflects a modular design that is easy to extend or modify.

##### Specific Technologies & Frameworks
- Browser APIs: Integration with Chrome’s extension APIs (e.g., context menus, messaging, extension events).
- JavaScript: All logic is implemented in JavaScript.
- HTML/CSS: Used in the popup for UI rendering.

- Content components interacting with web pages, receiving triggers (or events) from the Background scripts.
- Optionally, include an “External API Service” component, which the content scripts or background might contact using the user-provided API key/endpoint.
- Finally, incorporate the manifest.json as a central node that connects to all components, emphasizing its role in configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level User Interaction Layer
    subgraph "User Interaction Layer"
        U["User"]:::external
        PU["Popup UI"]:::popup
    end

    %% Background Processing Layer
    subgraph "Background Processing Layer"
        BS["Background Scripts"]:::background
    end

    %% Content Interaction Layer
    subgraph "Content Interaction Layer"
        CS["Content Scripts"]:::content
    end

    %% Configuration Layer
    subgraph "Configuration"
        MAN["Manifest"]:::config
        ASSET["Assets"]:::config
    end

    %% External API Service
    EA["External API Service"]:::external

    %% Connections
    U -->|"clickExtension"| PU
    PU -->|"setAPI"| BS
    BS -->|"contextMenuTrigger"| CS
    BS -->|"APIRequest"| EA
    CS -->|"responseMessage"| BS

    MAN ---|"configuration"| PU
    MAN ---|"configuration"| BS
    MAN ---|"configuration"| CS
    ASSET ---|"staticResources"| PU
    ASSET ---|"staticResources"| BS
    ASSET ---|"staticResources"| CS

    %% Styles
    classDef popup fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef background fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef content fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef config fill:#ffe4b5,stroke:#333,stroke-width:2px;
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:2px;

    %% Click Events for Popup UI Component
    click PU "https://github.com/hasan-py/ai-assistant-chrome-extension/blob/main/popup/index.html"
    click PU "https://github.com/hasan-py/ai-assistant-chrome-extension/blob/main/popup/popup.js"

    %% Click Events for Background Scripts
    click BS "https://github.com/hasan-py/ai-assistant-chrome-extension/blob/main/background/index.js"
    click BS "https://github.com/hasan-py/ai-assistant-chrome-extension/blob/main/background/contextMenuManager.js"
    click BS "https://github.com/hasan-py/ai-assistant-chrome-extension/blob/main/background/menus.js"

    %% Click Events for Content Scripts
    click CS "https://github.com/hasan-py/ai-assistant-chrome-extension/blob/main/content/index.js"
    click CS "https://github.com/hasan-py/ai-assistant-chrome-extension/blob/main/content/promptHandler.js"
    click CS "https://github.com/hasan-py/ai-assistant-chrome-extension/blob/main/content/promptUi.js"

    %% Click Events for Manifest and Assets
    click MAN "https://github.com/hasan-py/ai-assistant-chrome-extension/blob/main/manifest.json"
    click ASSET "https://github.com/hasan-py/ai-assistant-chrome-extension/tree/main/asset/"
```
