# deepsuthar496/domkeeper architecture

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

- Interactive diagram: https://gitdiagram.com/deepsuthar496/domkeeper
- Repository: https://github.com/deepsuthar496/domkeeper

## Overview

Step 1 – Project Type & Purpose
- This is a Chrome browser extension (“DOMKeeper”) that lets users make permanent, client-side DOM edits which persist across page reloads.
- Key indicators: manifest.json (Chrome extension), background.js, content.js, popup.html/js, README’s “Chrome Storage API” and “MutationObserver.”

Step 2 – File Structure Analysis
Top-level files:
- manifest.json – Registers extension components & permissions
- background.js – Persistent service worker/event handler
- content.js – Injected script that manipulates the page DOM
- popup.html & popup.js – UI for toggling edit mode and managing settings
- README.md – Project description, usage, tech stack

Patterns:
- Separation of concerns: UI (popup), background logic (background.js), page interaction (content.js).
- Event‐driven messaging via Chrome extension APIs.
- Persistent state in Chrome Storage.
- MutationObserver in content.js for dynamic content handling.

Step 3 – README Insights
- Architecture isn’t explicitly drawn, but it lists:
- Chrome Storage API → for persisting changes
- MutationObserver → to detect DOM changes
- Modern JavaScript

Step 4 – Main Components & Interactions
a. Components:
1. Popup UI (popup.html, popup.js)
2. Background script (background.js)
3. Content script (content.js)
4. Chrome Storage (chrome.storage.local)
5. Page DOM
6. Chrome Extension Messaging API

b. Relationships & Data Flow:
- User clicks popup → popup.js sends a chrome.runtime.sendMessage() to background.js
- background.js processes the command, updates chrome.storage, then sends a message to content.js in the active tab
- content.js receives the message → toggles edit mode or applies changes to the DOM
- content.js listens via MutationObserver for added/changed elements → reads/writes persistent data to chrome.storage to re-apply edits on refresh
- background.js may also listen for storage.onChanged to notify content scripts of setting updates

c. Architectural Patterns:
- Event-driven “message bus” using chrome.runtime.sendMessage / onMessage
- Publisher/subscriber for storage changes (chrome.storage.onChanged)
- Observer pattern for DOM mutations

d. Key Technologies:
- manifest.json (Extension manifest v3 spec)
- chrome.runtime & chrome.storage APIs
- MutationObserver in content.js
- Standard HTML/CSS/JS for popup

- Tri-layer separation: UI layer (popup), logic layer (background service worker), page layer (content script + DOM).
- Storage as a shared datastore accessible by background & content scripts.
- Message flows:
1. Popup → Background → Content
2. Content ↔ Storage
3. Background ↔ Storage (for centralized state updates)

Step 6 – Diagramming Guidelines
- Gray rectangle for Page DOM

Step 7 – Detail & Completeness
- Every script and its role.
- Lifecycle: extension installed → user toggles edit → storage updates → content script applies edits → page reload triggers re-application.
- Failure points (e.g., dynamic sites requiring multiple storage reads).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        Phtml["popup.html"]:::script
        Pjs["popup.js"]:::script
    end

    %% Background Layer
    subgraph "Background Layer"
        direction TB
        Bg["background.js"]:::script
    end

    %% Storage
    subgraph "Chrome Storage"
        direction TB
        Storage["chrome.storage.local"]:::storage
    end

    %% Content Layer
    subgraph "Content Layer"
        direction TB
        Content["content.js"]:::script
    end

    %% Page DOM
    Dom["Page DOM"]:::dom

    %% Documentation
    subgraph "Documentation"
        direction TB
        Mnf["manifest.json"]:::doc
        Readme["README.md"]:::doc
    end

    %% Connections
    Pjs -->|"chrome.runtime.sendMessage"| Bg
    Bg -->|"chrome.storage.get/set"| Storage
    Bg -->|"chrome.tabs.sendMessage"| Content
    Storage -->|"chrome.storage.onChanged"| Content
    Content -->|"chrome.storage.get/set"| Storage
    Dom -->|"MutationObserver callback"| Content

    %% Legend (as subgraph)
    subgraph "Legend"
        direction TB
        Script["Script Files"]:::script
        Store["Storage"]:::storage
        Page["Page DOM"]:::dom
        Doc["Docs"]:::doc
    end

    %% Click Events
    click Phtml "https://github.com/deepsuthar496/domkeeper/blob/main/popup.html"
    click Pjs "https://github.com/deepsuthar496/domkeeper/blob/main/popup.js"
    click Bg "https://github.com/deepsuthar496/domkeeper/blob/main/background.js"
    click Content "https://github.com/deepsuthar496/domkeeper/blob/main/content.js"
    click Mnf "https://github.com/deepsuthar496/domkeeper/blob/main/manifest.json"
    click Readme "https://github.com/deepsuthar496/domkeeper/blob/main/README.md"

    %% Styles
    classDef script fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef storage fill:#98FB98,stroke:#000,stroke-width:1px
    classDef dom fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef doc fill:#FFFACD,stroke:#000,stroke-width:1px
```
