# umerhd/gptrules architecture

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

- Interactive diagram: https://gitdiagram.com/umerhd/gptrules
- Repository: https://github.com/umerhd/gptrules

## Overview

##### Project Type and Purpose
- This is a browser extension built to inject custom “GPT Rules” into web pages. It leverages background scripts, content scripts, and a popup user interface to integrate with AI chat experiences.
- The README highlights features like “Custom Commands”, “Cursor-Style Prompting”, and “Browser Integration”. These are central to the function and are reflected in the division of source code into background, content, and popup modules.

##### File Structure
- Top-level configuration files (package.json, tsconfig.json, webpack.config.js, tailwind.config.js) indicate a TypeScript-based project with a bundling & style configuration.
- The src directory is organized by functionality:
- src/background contains the background script (background.ts) and default rules (defaultRules.ts).
- src/content holds various scripts (e.g., ContentEditableHandler, PopupManager, RulesInjector, etc.) that facilitate content script interactions (injection into web pages, handling text areas, and managing popups).
- src/popup contains the HTML and TSX for the popup interface.
- src/types provides TypeScript type definitions.
- The dist folder corresponds to compiled output for distribution and is used for Chrome extension installation (as detailed in the README).

##### Key Components to Highlight
a. Chrome Extension Manifest and Packaging
- A “Manifest” block representing manifest.json (both in dist and top-level manifest.json) which is the configuration entry point for the browser.
b. Background Script
- “Background” component (src/background/background.ts and defaultRules.ts). This script establishes global extension behaviors, manages state, and handles events that may not be tied directly to any tab.
c. Content Script
d. Popup UI
e. Build & Dependency Components
- A small section for “Build Tools” that covers webpack (webpack.config.js), TypeScript (tsconfig.json), and Tailwind CSS (tailwind.config.js, postcss.config.js). This gives context around the developer workflow and build process.

##### Relationships and Interactions
- Data flow starting from the Manifest which instructs the browser to load the Background Script, Content Script, and Popup UI.
– From Manifest to load Background and Content Scripts.
– Optionally, denote potential interactions between the Background Script and Content Script for managing shared state or message-passing between tabs.

##### Architectural Patterns & Design Principles
- Separation of concerns: The project is modularized into background, content, and popup components.
- That the project follows typical Chrome extension design patterns where:
– The Manifest acts as the configuration and entry point.
– The Background script is persistent and handles global events.
– The Content script directly manipulates the web page’s DOM.
– The Popup is a standalone UI component invoked on user action.
- Mention that TypeScript and React (through TSX) are used, promoting type safety and component-based UI design.

## Diagram (Mermaid)

```mermaid
graph TD
    A["Browser Extension Loader"]:::loader
    B["Manifest"]:::manifest
    C["Background Script"]:::background
    D["Content Script"]:::content
    E["Popup UI"]:::popup
    F["Build Tools & Configurations"]:::build

    %% Subgraphs for detailed components
    subgraph "Background Script"
        C1["background.ts"]:::backgroundfile
        C2["defaultRules.ts"]:::backgroundfile
    end

    subgraph "Content Script"
        D1["ContentEditableHandler.ts"]:::contentfile
        D2["PopupManager.ts"]:::contentfile
        D3["RulesInjector.ts"]:::contentfile
        D4["TextAreaHandler.ts"]:::contentfile
        D5["content.ts"]:::contentfile
    end

    subgraph "Popup UI"
        E1["popup.html"]:::popupfile
        E2["popup.tsx"]:::popupfile
    end

    subgraph "Build Tools & Configurations"
        F1["webpack.config.js"]:::buildfile
        F2["tsconfig.json"]:::buildfile
        F3["tailwind.config.js"]:::buildfile
        F4["postcss.config.js"]:::buildfile
        F5["package.json"]:::buildfile
    end

    %% Relationships
    A -->|"load"| B
    B -->|"init"| C
    B -->|"init"| D
    B -->|"launch"| E
    C -->|"message"| D
    D -->|"invokes"| E
    F -->|"builds"| B

    %% Click Events for Manifest (both top-level and dist)
    click B "https://github.com/umerhd/gptrules/blob/main/manifest.json"
    click B "https://github.com/umerhd/gptrules/blob/main/dist/manifest.json"

    %% Click Events for Background Script
    click C1 "https://github.com/umerhd/gptrules/blob/main/src/background/background.ts"
    click C2 "https://github.com/umerhd/gptrules/blob/main/src/background/defaultRules.ts"

    %% Click Events for Content Script
    click D1 "https://github.com/umerhd/gptrules/blob/main/src/content/ContentEditableHandler.ts"
    click D2 "https://github.com/umerhd/gptrules/blob/main/src/content/PopupManager.ts"
    click D3 "https://github.com/umerhd/gptrules/blob/main/src/content/RulesInjector.ts"
    click D4 "https://github.com/umerhd/gptrules/blob/main/src/content/TextAreaHandler.ts"
    click D5 "https://github.com/umerhd/gptrules/blob/main/src/content/content.ts"

    %% Click Events for Popup UI
    click E1 "https://github.com/umerhd/gptrules/blob/main/src/popup/popup.html"
    click E2 "https://github.com/umerhd/gptrules/blob/main/src/popup/popup.tsx"

    %% Click Events for Build Tools & Configurations
    click F1 "https://github.com/umerhd/gptrules/blob/main/webpack.config.js"
    click F2 "https://github.com/umerhd/gptrules/blob/main/tsconfig.json"
    click F3 "https://github.com/umerhd/gptrules/blob/main/tailwind.config.js"
    click F4 "https://github.com/umerhd/gptrules/blob/main/postcss.config.js"
    click F5 "https://github.com/umerhd/gptrules/blob/main/package.json"

    %% Styles
    classDef loader fill:#f2d7d5,stroke:#e74c3c,stroke-width:2px,color:#000;
    classDef manifest fill:#d5e8d4,stroke:#82b366,stroke-width:2px,color:#000;
    classDef background fill:#cce5ff,stroke:#339af0,stroke-width:2px,color:#000;
    classDef backgroundfile fill:#99d6ff,stroke:#339af0,stroke-width:1px;
    classDef content fill:#fff3bf,stroke:#f6c343,stroke-width:2px,color:#000;
    classDef contentfile fill:#ffe066,stroke:#f6c343,stroke-width:1px;
    classDef popup fill:#d5e8d4,stroke:#82b366,stroke-width:2px,color:#000;
    classDef popupfile fill:#b2d8b2,stroke:#82b366,stroke-width:1px;
    classDef build fill:#f0f0f0,stroke:#999,stroke-width:2px,color:#000;
    classDef buildfile fill:#e0e0e0,stroke:#999,stroke-width:1px;
```
