# h120/ai-chat-scroller architecture

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

- Interactive diagram: https://gitdiagram.com/h120/ai-chat-scroller
- Repository: https://github.com/h120/ai-chat-scroller

## Overview

##### Project Type and Purpose
- Type: Browser extension (Chrome).
- Purpose: Enhance AI chat UIs (ChatGPT, Grok, Claude) by auto‑numbering messages, adding scroll buttons, and toggling visibility while persisting state across sessions.

##### File Structure
- manifest.json: Extension metadata, content_script definitions (injection targets), permissions (storage).
- aiscroller.js: The single content script implementing UI injection, event handlers, state persistence.
- Readme.md: Describes features, supported platforms, installation.

##### Extract Key Architectural Insights from README
- No external backend—logic runs entirely in the browser.
- Runs only on supported chat URLs via manifest match patterns.
- Uses Chrome’s storage API to remember UI state.
- UI elements (buttons, number labels) are injected into host page DOM.

##### Main Components
a. Browser & Extension Shell
- Chrome Extension Loader (manifest.json)
- chrome.runtime & chrome.storage APIs
b. Content Script
- aiscroller.js logic
- DOM injection of:
- Numbered labels on AI messages
- Up/Down scroll buttons
- Toggle‑visibility button
c. Host Web Pages (External Services)
- ChatGPT (chat.openai.com/*)
- Grok (grok.com/chat/*)
- Claude (claude.ai/chat/*)
d. Persistent Storage
- chrome.storage.local (persists visibility on/off)

##### Relationships and Interactions
- Manifest → registers content script on matching URLs.
- Chrome loads aiscroller.js into each matching tab.
- Content Script:
1. Scans DOM for AI messages → adds ordinal labels.
2. Injects control UI (buttons) → listens for click events.
3. On scroll-button click → scrolls container up/down.
4. On toggle click → shows/hides UI → writes state to chrome.storage.
5. On page load → reads chrome.storage to set initial visibility.
- Browser Storage ↔ Content Script: get/set visibility flag.
- User ↔ Injected UI: interacts via injected buttons.

##### Architectural Patterns and Principles
- Event‑driven: reacts to DOM mutations and user events.
- Single responsibility: aiscroller.js handles all logic—no background/service worker.
- Declarative manifest: defines injection points and permissions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Extension Core
    Manifest["manifest.json"]:::extension
    Readme["Readme.md"]:::documentation
    Assets["images/"]:::assets

    %% Content Script
    ContentScript["aiscroller.js (Content Script)"]:::content
    Storage["chrome.storage API"]:::storage
    UIControls["Injected UI Elements"]:::ui

    %% Supported AI Platforms
    subgraph "Supported AI Platforms"
        ChatGPT["ChatGPT (chat.openai.com/*)"]:::external
        Grok["Grok (grok.com/chat/*)"]:::external
        Claude["Claude (claude.ai/chat/*)"]:::external
    end

    %% Interactions
    Manifest -->|"registers content_script"| ContentScript
    ContentScript -->|"injects UI into DOM"| ChatGPT
    ContentScript -->|"injects UI into DOM"| Grok
    ContentScript -->|"injects UI into DOM"| Claude
    ContentScript -->|"readState"| Storage
    ContentScript -->|"writeState"| Storage
    ContentScript -->|"renders controls"| UIControls
    UIControls -->|"user events"| ContentScript

    %% Click Events
    click Manifest "https://github.com/h120/ai-chat-scroller/blob/main/manifest.json"
    click ContentScript "https://github.com/h120/ai-chat-scroller/blob/main/aiscroller.js"
    click Storage "https://github.com/h120/ai-chat-scroller/blob/main/aiscroller.js"
    click Readme "https://github.com/h120/ai-chat-scroller/blob/main/Readme.md"
    click Assets "https://github.com/h120/ai-chat-scroller/tree/main/images/"

    %% Styles
    classDef extension fill:#FFA500,stroke:#333,stroke-width:1px
    classDef content fill:#90EE90,stroke:#333,stroke-width:1px
    classDef storage fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef documentation fill:#FFD700,stroke:#333,stroke-width:1px
    classDef assets fill:#FFA07A,stroke:#333,stroke-width:1px
    classDef ui fill:#E6E6FA,stroke:#333,stroke-width:1px
```
