# swerve145/ai-reflector architecture

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

- Interactive diagram: https://gitdiagram.com/swerve145/ai-reflector
- Repository: https://github.com/swerve145/ai-reflector

## Overview

##### Project Type and Purpose
- This is a Chrome extension (“AI Reflection Helper”) designed to inject active‐learning prompts into the ChatGPT web UI.
- Its goal is to require students to reflect on AI‐generated answers before proceeding, boosting retention.

##### File Structure Analysis
- Top-level files:
- README.md – project overview and install instructions
- ai-reflector/ directory:
- manifest.json – extension metadata, permissions, content scripts, UI entries
- content.js – content script that runs in the context of chat.openai.com; watches for new responses and injects reflection prompts
- popup.html & popup.js – the toolbar popup UI (e.g., settings or brief guide)
- guide.html – a standalone help page explaining usage
- styles.css – shared styling for injected prompts and UIs

##### Key Insights from README
- No external backend or server component: everything runs client-side in the browser.
- Users load it via “Load unpacked” in Chrome; it operates by modifying the ChatGPT page DOM.

##### Main Components
a. Chrome Browser Host
b. Extension Manifest (manifest.json) – declares:
- Permissions (e.g., activeTab, storage)
- Content Script injection rules (match patterns for chat.openai.com)
- Browser action (popup) entry point
c. Content Script (content.js)
- Listens for DOM changes in the ChatGPT response area
- Injects a reflection prompt module into the page
- Reads/writes user settings via chrome.storage
- Optionally opens guide.html in a new tab
d. Popup UI (popup.html + popup.js)
- Provides on-click settings or quick guide access
- Communicates with content script via chrome.runtime.sendMessage or chrome.storage
e. Shared Resources
- styles.css for consistent styling
- guide.html loaded as a help page
f. User Interaction
- End user reads ChatGPT responses
- Content script pauses flow and displays prompt UI for reflection
- User’s input is collected before allowing continuation

##### Relationships and Data Flow
2. Popup may read/write settings via chrome.storage
3. User navigates to chat.openai.com → Manifest injects content.js
4. content.js detects new AI responses (DOM MutationObserver)
5. content.js inserts reflection prompt UI (styled by styles.css)
6. User enters reflection → content.js saves to chrome.storage (optional)
7. Once submitted, content.js re-enables the ChatGPT “Continue” button

##### Architectural Patterns & Principles
- Single-Page Integration: content.js hooks into a third-party SPA (ChatGPT)
- Event-Driven: DOM events/mutations trigger reflection UI
- Client-Only, No Server: all logic and data reside in-browser, leveraging chrome.storage
- Clear Separation of Concerns:
- manifest.json defines wiring
- content script handles page augmentation
- popup handles configuration
- CSS & guide page are shared assets

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Chrome Browser Host" 
        direction TB
        B["Chrome Browser Host"]:::chromeApi
        CG["ChatGPT Web App"]:::thirdparty
    end

    U["End User"]:::user
    M["Manifest (manifest.json)"]:::extension
    CS["Content Script (content.js)"]:::extension
    PU["Popup UI (popup.html + popup.js)"]:::extension
    S["chrome.storage API"]:::chromeApi
    ASub["Styles (styles.css)"]:::assets
    G["Guide Page (guide.html)"]:::assets
    ST["README (README.md)"]:::assets

    U -->|"click extension icon"| PU
    PU -->|"chrome.storage.get/set"| S
    PU -->|"message passing"| CS

    M -->|"load unpacked / installation"| B
    M -->|"defines permissions & injection rules"| B

    B -->|"inject content.js on match patterns"| CS
    CS -->|"MutationObserver: detect new AI responses"| CG
    CS -->|"inject reflection prompt UI"| CG
    CS -->|"read/write settings"| S
    CS -->|"open guide page in new tab"| G
    CS -->|"re-enable Continue button"| CG

    U -->|"reads AI responses"| CG
    CG -->|"user input reflection"| CS

    PU -->|"open guide"| G
    CS -->|"use shared styles"| ASub

    ST

    click M "https://github.com/swerve145/ai-reflector/blob/main/ai-reflector/manifest.json"
    click CS "https://github.com/swerve145/ai-reflector/blob/main/ai-reflector/content.js"
    click PU "https://github.com/swerve145/ai-reflector/blob/main/ai-reflector/popup.html"
    click PU "https://github.com/swerve145/ai-reflector/blob/main/ai-reflector/popup.js"
    click ASub "https://github.com/swerve145/ai-reflector/blob/main/ai-reflector/styles.css"
    click G "https://github.com/swerve145/ai-reflector/blob/main/ai-reflector/guide.html"
    click ST "https://github.com/swerve145/ai-reflector/blob/main/README.md"

    classDef chromeApi fill:#AED6F1,stroke:#2E86C1,color:#1B4F72
    classDef extension fill:#ABEBC6,stroke:#239B56,color:#1D8348
    classDef assets fill:#E5E7E9,stroke:#7B7D7D,color:#424949
    classDef thirdparty fill:#D5DBDB,stroke:#909497,color:#626567
    classDef user fill:#F9E79F,stroke:#B7950B,color:#7D6608
```
