# naeha-s/chatbridge architecture

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

- Interactive diagram: https://gitdiagram.com/naeha-s/chatbridge
- Repository: https://github.com/naeha-s/chatbridge

## Overview

##### Project type and purpose
- ChatBridge is a Chrome extension (Manifest V3) that “bridges” AI conversations across multiple web platforms (ChatGPT, Claude, Gemini, Copilot, etc.). It scans chat DOMs, uses adapter modules to extract messages, invokes AI services for transformation (summaries, rewrites, translations), and maintains a local “connected memory graph” of insights.

##### File structure
- Top-level manifest.json declares extension permissions, content scripts, background service worker, and UI pages.
- content_script.js (and BACKUP) plus adapters.js implement page-scanning logic, platform-specific extractors.
- background.js (service worker) handles long-running tasks: API calls (ai_client.js), chunking/processing (aiUtils.js, ragEngine.js), error fixing (auto_fix.js, fix_errors.js), bridge logic (mcpBridge.js).
- storage.js wraps Chrome Storage API + LocalStorage fallback.
- popup.html/js, sidebar.html/js, options.html/js, summarize_tab.html/js are the front-end UI surfaces.
- documentation/ holds deep-dive architecture, API reference, developer guide, features, security, troubleshooting.
- Scripts like restore_mvp.ps1 and .github configuration are ancillary.

##### README for additional insights
- Describes adapter • observer • strategy • singleton patterns.
- Outlines core features: extraction, tone syncing, summarization, rewriting, translation, memory graph, contradiction tracking, multi-hop discovery, smart query, export/import.
- Tech stack: vanilla JS, Canvas, Shadow DOM, Chrome Storage API, Google Gemini API, parallel processing pipelines.

##### Main components
a. Content Script & Adapter Layer
- content_script.js + adapters.js scan page DOM, filter UI elements, distinguish user/assistant messages.
b. Background Processing & AI Bridge
- background.js coordinates tasks; invokes ai_client.js (API wrappers), aiUtils.js (chunking, retries), ragEngine.js (memory graph), mcpBridge.js (cross-context memory).
c. Storage Layer
- storage.js abstracts Chrome Storage API & LocalStorage fallback; persists conversations, memory graph, settings.
d. UI Components
- Popup (popup.html/js), Sidebar (sidebar.html/js), Summarize Tab (summarize_tab.html/js), Options (options.html/js) provide user entry points to functions.
e. External Services
- Google Gemini API (and other AI model endpoints via ai_client.js), optionally user-provided keys.
f. Static Assets & Config

##### Relationships and interactions
- Popup asks content script to “scan chat” → content script uses adapters to extract messages → sends extracted payload to background.
- Background invokes AI services (via ai_client) → processes responses (aiUtils, auto_fix, fix_errors) → stores results in storage.
- Sidebar UI listens for storage changes (Observer pattern) → retrieves data (memory graph, summaries) → renders via Canvas.
- Summarize Tab UI similarly requests background for summaries.
- Options UI reads/writes settings to storage (Singleton pattern for config).
- Background monitors storage changes to maintain memory graph and contradiction tracking (Observer pattern).
- Export/Import UI calls background to read/write JSON snapshots.

##### Architectural patterns and design principles
- Adapter pattern: adapters.js encapsulates platform-specific DOM parsing.
- Observer pattern: storage events notify UIs (sidebar, popup) of state changes.
- Strategy pattern: aiUtils and ragEngine select summarization, translation, rewriting strategies.
- Singleton pattern: storage.js, ai_client.js hold single instances of storage and API clients.

##### Crucial details to capture
- manifest.json roles: permissions, background script, content script matches.
- Extraction adapters per platform.
- Parallel summarization pipeline (aiUtils + Promise.all).
- Memory graph engine (ragEngine).
- Retry & fallback logic (auto_fix, fix_errors).
- Local-first, encrypted API key storage.
- UI isolation via Shadow DOM.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Content Script Layer"
        CS1["content_script.js"]:::contentStyle
        CS2["content_script_BACKUP.js"]:::contentStyle
        CS3["content.js"]:::contentStyle
        ADP["adapters.js"]:::contentStyle
    end

    subgraph "Background Processing & AI Bridge"
        BG["background.js"]:::backgroundStyle
        AI["ai_client.js"]:::backgroundStyle
        AU["aiUtils.js"]:::backgroundStyle
        RG["ragEngine.js"]:::backgroundStyle
        MB["mcpBridge.js"]:::backgroundStyle
        AF["auto_fix.js"]:::backgroundStyle
        FE["fix_errors.js"]:::backgroundStyle
    end

    subgraph "Storage Layer"
        ST["storage.js"]:::storageStyle
    end

    subgraph "UI Components"
        PP["popup.html"]:::uiStyle
        PJ["popup.js"]:::uiStyle
        SP["sidebar.html"]:::uiStyle
        SJ["sidebar.js"]:::uiStyle
        OP["options.html"]:::uiStyle
        OJ["options.js"]:::uiStyle
        TP["summarize_tab.html"]:::uiStyle
        TJ["summarize_tab.js"]:::uiStyle
    end

    subgraph "External AI Services"
        API["Google Gemini API / AI endpoints"]:::externalStyle
    end

    subgraph "Static Assets & Config"
        MN["manifest.json"]:::uiStyle
        IC["icons/"]:::uiStyle
        STY["styles.css"]:::uiStyle
        DOC["documentation/"]:::uiStyle
    end

    PP -->|loads| PJ
    PJ -->|"scanRequest"| CS1
    PJ -->|"sendMessage"| BG
    CS1 -->|"useAdapter"| ADP
    CS1 -->|"extractedData"| BG
    BG -->|"aiTransform"| AI
    AI -->|"responseData"| BG
    BG -->|"processChunks"| AU
    BG -->|"updateMemoryGraph"| RG
    BG -->|"bridgeMemory"| MB
    BG -->|"autoFixPipeline"| AF
    BG -->|"errorCorrection"| FE
    BG -->|"persist"| ST
    ST -->|"storageUpdate"| SJ
    SJ -->|"renderUI"| SP
    TJ -->|"requestSummary"| BG
    OJ -->|"readWriteSettings"| ST

    click CS1 "https://github.com/naeha-s/chatbridge/blob/main/content_script.js"
    click CS2 "https://github.com/naeha-s/chatbridge/blob/main/content_script_BACKUP.js"
    click CS3 "https://github.com/naeha-s/chatbridge/blob/main/content.js"
    click ADP "https://github.com/naeha-s/chatbridge/blob/main/adapters.js"
    click BG "https://github.com/naeha-s/chatbridge/blob/main/background.js"
    click AI "https://github.com/naeha-s/chatbridge/blob/main/ai_client.js"
    click AU "https://github.com/naeha-s/chatbridge/blob/main/aiUtils.js"
    click RG "https://github.com/naeha-s/chatbridge/blob/main/ragEngine.js"
    click MB "https://github.com/naeha-s/chatbridge/blob/main/mcpBridge.js"
    click AF "https://github.com/naeha-s/chatbridge/blob/main/auto_fix.js"
    click FE "https://github.com/naeha-s/chatbridge/blob/main/fix_errors.js"
    click ST "https://github.com/naeha-s/chatbridge/blob/main/storage.js"
    click PP "https://github.com/naeha-s/chatbridge/blob/main/popup.html"
    click PJ "https://github.com/naeha-s/chatbridge/blob/main/popup.js"
    click SP "https://github.com/naeha-s/chatbridge/blob/main/sidebar.html"
    click SJ "https://github.com/naeha-s/chatbridge/blob/main/sidebar.js"
    click OP "https://github.com/naeha-s/chatbridge/blob/main/options.html"
    click OJ "https://github.com/naeha-s/chatbridge/blob/main/options.js"
    click TP "https://github.com/naeha-s/chatbridge/blob/main/summarize_tab.html"
    click TJ "https://github.com/naeha-s/chatbridge/blob/main/summarize_tab.js"
    click MN "https://github.com/naeha-s/chatbridge/blob/main/manifest.json"
    click IC "https://github.com/naeha-s/chatbridge/tree/main/icons/"
    click STY "https://github.com/naeha-s/chatbridge/blob/main/styles.css"
    click DOC "https://github.com/naeha-s/chatbridge/tree/main/documentation/"

    classDef contentStyle fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backgroundStyle fill:#90EE90,stroke:#333,stroke-width:1px
    classDef storageStyle fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef uiStyle fill:#FFA500,stroke:#333,stroke-width:1px
    classDef externalStyle fill:#D3D3D3,stroke:#333,stroke-width:1px
```
