# abhimanyu08/rabbit-hole-extension architecture

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

- Interactive diagram: https://gitdiagram.com/abhimanyu08/rabbit-hole-extension
- Repository: https://github.com/abhimanyu08/rabbit-hole-extension

## Overview

##### Project type and purpose
- This is a browser extension (Chrome) that tracks “rabbit hole” browsing sessions.
- It captures every link click, tab switch, and URL change between a user-initiated start/stop toggle, then visualizes each session on a standalone history page with D3.

##### File structure analysis
- manifest.json: Chrome extension manifest, defines permissions, background script, UI pages.
- background.js: long-running background script that listens for tab and URL events, manages session start/stop, writes to storage.
- popup.html / popup.js: small UI in the toolbar to toggle session tracking.
- history.html / history.js / history.css: standalone “chrome://history” replacement page that reads stored sessions and renders them with D3.
- d3.v7.js: D3 library for building the session graph.
- .gitignore, README.md: project metadata.

##### Key README insights
- A checkbox in the popup starts/stops a “rabbit hole session.”
- background.js captures all navigation and tab events only while tracking is enabled.
- history.html displays sessions in a grid; users can name, expand, delete sessions; nodes are clickable links.
- Future enhancements mention link types (redirect vs. tab switch), notes, sharing, and tree-style visualization.

##### Main components to illustrate
- Chrome Browser UI
- Extension toolbar (popup)
- History page (custom UI)
- Extension core
- manifest.json (declarations & permissions)
- background.js (event listeners, session manager, storage API)
- chrome.storage.local (or storage API bucket)
- User interfaces
- popup.html/js (toggle control)
- history.html/css/js + d3.v7.js (visualization engine)

##### Relationships and data flow
- User clicks popup checkbox → popup.js sends message to background.js to start/stop session.
- background.js registers chrome.tabs.onUpdated and chrome.tabs.onActivated listeners.
- On each tab event, background.js writes a record (timestamp, URL, event type, session ID) into chrome.storage.local.
- User opens history.html → history.js reads all sessions from storage, processes into grids, passes data into D3 to render nodes and links.
- Click events in history visualization open new tabs via window.open and optionally update the same session in storage.

##### Architectural patterns & design principles
- Event-driven background service: background.js acts as the single source of truth for session state.
- Message passing between UI (popup/history) and background via chrome.runtime.sendMessage / onMessage.
- Separation of concerns:
- Tracking logic in background.js
- Presentation in popup.js and history.js
- Data storage isolated in chrome.storage API
- Visualization layer uses D3 to map JSON session data to SVG/HTML.

##### Key callouts for the principal software engineer
- Clearly delineate each component’s responsibility.
- Event sources–listeners in background.js, and message flows.
- Absence of a remote backend; all data lives in the user’s local Chrome storage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Chrome Browser UI"
        popupHTML["popup.html"]:::ui
        popupJS["popup.js"]:::ui
        historyHTML["history.html"]:::ui
        historyJS["history.js"]:::ui
        historyCSS["history.css"]:::ui
    end

    manifest["manifest.json"]:::other
    background["background.js"]:::background
    storage[(chrome.storage.local)]:::storage
    d3["d3.v7.js"]:::lib
    readme["README.md"]:::other
    gitignore[".gitignore"]:::other

    manifest -->|"declares UI pages & background"| popupHTML
    manifest -->|"declares UI pages & background"| historyHTML
    manifest -->|"declares UI pages & background"| background

    popupJS -.-|"sendMessage start/stop"| background
    background -->|"write session record"| storage
    historyJS -->|"read sessions"| storage

    historyJS -->|"loads library"| d3

    readme -.-> manifest
    gitignore -.-> manifest

    classDef ui fill:#89CFF0,stroke:#333,stroke-width:1px;
    classDef background fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef storage fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef lib fill:#9370DB,stroke:#333,stroke-width:1px;
    classDef other fill:#D3D3D3,stroke:#333,stroke-width:1px;

    click manifest "https://github.com/abhimanyu08/rabbit-hole-extension/blob/main/manifest.json"
    click background "https://github.com/abhimanyu08/rabbit-hole-extension/blob/main/background.js"
    click popupHTML "https://github.com/abhimanyu08/rabbit-hole-extension/blob/main/popup.html"
    click popupJS "https://github.com/abhimanyu08/rabbit-hole-extension/blob/main/popup.js"
    click historyHTML "https://github.com/abhimanyu08/rabbit-hole-extension/blob/main/history.html"
    click historyJS "https://github.com/abhimanyu08/rabbit-hole-extension/blob/main/history.js"
    click historyCSS "https://github.com/abhimanyu08/rabbit-hole-extension/blob/main/history.css"
    click d3 "https://github.com/abhimanyu08/rabbit-hole-extension/blob/main/d3.v7.js"
    click readme "https://github.com/abhimanyu08/rabbit-hole-extension/blob/main/README.md"
    click gitignore "https://github.com/abhimanyu08/rabbit-hole-extension/blob/main/.gitignore"
```
