# ahmedamine12/extention_easyai_chat architecture

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

- Interactive diagram: https://gitdiagram.com/ahmedamine12/extention_easyai_chat
- Repository: https://github.com/ahmedamine12/extention_easyai_chat

## Overview

##### Project Type and Purpose
- This is a browser extension (Chrome/Chromium-based) named “EasyAI Chat.”
- Purpose: inject an AI-powered floating chat interface into any webpage, manage API keys locally, and route user queries to OpenAI or Google Gemini directly from the client.

##### File-Structure Analysis
- manifest.json: extension’s entry point (permissions, scripts, UI).
- background.js: event-driven service worker handling long-lived tasks, message routing, API calls.
- content.js & homepage.html: injection of the floating chat bubble and main in-page UI.
- popup/ (popup.html, popup.js, popup.css): the click-to-open toolbar popup.
- settings/ (settings.html, settings.js, settings.css): configuration UI for API keys, preferences.
- providers/ (openai.js, gemini.js): modules encapsulating remote API endpoints and request logic.
- utils/ (storage.js, crypto.js, error.js): local storage abstraction, encryption routines, error handling.

##### Insights from README
- No backend servers—everything runs in the browser.
- Privacy-first: keys encrypted locally; local storage only.
- Communication pattern: UI ↔ background.js ↔ external AI APIs.

- Browser Host (represents user’s Chrome/Edge/Vivaldi)
- Content Script Module (content.js + homepage.html)
- Popup UI Module (popup/)
- Settings UI Module (settings/)
- Background Service Worker (background.js)
- Storage & Crypto Utils (utils/storage.js & utils/crypto.js)
- Provider Modules (providers/openai.js & providers/gemini.js)
- Local Storage (chrome.storage + IndexedDB if used)
- External AI Services (OpenAI, Google Gemini)
1. User clicks bubble or context-menu → content.js captures input → sends “QUERY” message to background.js
2. Popup UI → sends “QUERY” or “FETCH_HISTORY” to background.js
3. Settings UI → reads/writes encrypted keys via background.js → utils/storage.js → chrome.storage
4. background.js receives “QUERY” → routes to appropriate provider module → provider builds HTTP request → external AI service → returns JSON → background.js processes errors (utils/error.js) → stores history (utils/storage.js) → responds to sender UI
5. background.js dispatches result → content.js or popup.js → render in homepage.html or popup.html
c. Architectural Patterns & Principles
- Event-driven messaging (chrome.runtime.sendMessage/onMessage)
- Separation of concerns: UI layers (content/popup/settings) vs service logic (background) vs data modules (providers/utils)
- Privacy by design: encryption of keys, zero remote logging
d. Key Technologies & Frameworks
- Chrome Extension Manifest v3 APIs (runtime, storage, contextMenus)
- vanilla JavaScript + CSS for UIs
- Fetch API for external HTTP requests
- Web Crypto API (utils/crypto.js)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Extension Entry Point"
        Manifest["manifest.json"]:::data
        Styles["styles.css"]:::data
    end

    subgraph "UI Components"
        subgraph "Content Script Module"
            ContentUI["content.js / homepage.html"]:::ui
        end
        subgraph "Popup UI Module"
            PopupHTML["popup.html"]:::ui
            PopupJS["popup.js"]:::ui
            PopupCSS["popup.css"]:::ui
        end
        subgraph "Settings UI Module"
            SettingsHTML["settings.html"]:::ui
            SettingsJS["settings.js"]:::ui
            SettingsCSS["settings.css"]:::ui
        end
    end

    Background["background.js"]:::service

    subgraph "Provider Modules"
        OpenAI["openai.js"]:::data
        Gemini["gemini.js"]:::data
    end

    subgraph "Storage & Crypto Utils"
        Storage["storage.js"]:::data
        Crypto["crypto.js"]:::data
        Error["error.js"]:::data
    end

    LocalStorage["chrome.storage / IndexedDB"]:::data
    External["External AI Services\n(OpenAI, Google Gemini)"]:::external

    %% Data Flows
    ContentUI -->|"QUERY_REQUEST"| Background
    PopupJS -->|"QUERY_REQUEST / FETCH_HISTORY"| Background
    SettingsJS -->|"SAVE_KEY / LOAD_KEY"| Background

    Background -->|"encrypt/decrypt"| Crypto
    Background -->|"read/write"| Storage
    Background -->|"handle errors"| Error

    Background -->|"HTTP Request"| OpenAI
    Background -->|"HTTP Request"| Gemini

    OpenAI -->|"API_RESPONSE"| Background
    Gemini -->|"API_RESPONSE"| Background

    Background -->|"store history"| Storage
    Background -->|"return result"| ContentUI
    Background -->|"return result"| PopupJS

    Storage -->|"persist data"| LocalStorage
    Crypto -->|"use Web Crypto API"| LocalStorage

    Background -->|"uses manifest config"| Manifest

    Background -->|"apply styles"| Styles

    Background --> External

    %% Click Events
    click ContentUI "https://github.com/ahmedamine12/extention_easyai_chat/blob/master/content.js"
    click PopupHTML "https://github.com/ahmedamine12/extention_easyai_chat/blob/master/popup/popup.html"
    click PopupJS "https://github.com/ahmedamine12/extention_easyai_chat/blob/master/popup/popup.js"
    click PopupCSS "https://github.com/ahmedamine12/extention_easyai_chat/blob/master/popup/popup.css"
    click SettingsHTML "https://github.com/ahmedamine12/extention_easyai_chat/blob/master/settings/settings.html"
    click SettingsJS "https://github.com/ahmedamine12/extention_easyai_chat/blob/master/settings/settings.js"
    click SettingsCSS "https://github.com/ahmedamine12/extention_easyai_chat/blob/master/settings/settings.css"
    click Background "https://github.com/ahmedamine12/extention_easyai_chat/blob/master/background.js"
    click OpenAI "https://github.com/ahmedamine12/extention_easyai_chat/blob/master/providers/openai.js"
    click Gemini "https://github.com/ahmedamine12/extention_easyai_chat/blob/master/providers/gemini.js"
    click Storage "https://github.com/ahmedamine12/extention_easyai_chat/blob/master/utils/storage.js"
    click Crypto "https://github.com/ahmedamine12/extention_easyai_chat/blob/master/utils/crypto.js"
    click Error "https://github.com/ahmedamine12/extention_easyai_chat/blob/master/utils/error.js"
    click Manifest "https://github.com/ahmedamine12/extention_easyai_chat/blob/master/manifest.json"
    click Styles "https://github.com/ahmedamine12/extention_easyai_chat/blob/master/styles.css"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef service fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
