# shubh-14-cloud/quantumtabs architecture

> Architecture diagram of the GitHub repository shubh-14-cloud/quantumtabs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shubh-14-cloud/quantumtabs
- Repository: https://github.com/shubh-14-cloud/quantumtabs

## Overview

1. **Project type and scope**
   - QuantumTabs is a **Chrome extension**, not a standalone app or service.
   - Its purpose is to **track time spent on browser tabs**, apply **filters**, and present **visualizations**.

2. **Extension entry points**
   - `manifest.json` is the top-level wiring file for the extension.
   - It defines the extension’s runtime permissions, background entry, popup UI, settings/options UI, and any browser action behavior.

3. **Core tracking subsystem**
   - `background.js` is the most important architectural component.
   - It likely acts as the **central event-driven tracker** for tab activity, accumulating time spent per tab/site and maintaining the canonical state for usage data.
   - In a Chrome extension like this, the background script is typically where tab switch, window focus, and navigation events are observed.

4. **User-facing control surface**
   - `popup.html`, `popup.css`, and `popup.js` form the **primary lightweight UI** opened from the extension icon.
   - This is likely the “at a glance” view: current timer status, recent tab stats, and quick actions.
   - The popup is a narrow interaction boundary; it should not own long-lived state.

5. **Configuration and analytics surface**
   - `settings.html`, `settings.css`, and `settings.js` provide a **deeper configuration/analysis view**.
   - This is where advanced filtering and visualization-related preferences are likely managed.
   - The settings page probably reads from and writes to the same persistent state used by the tracker.

6. **Data flow between components**
   - The primary flow is likely:
     - **Browser tab events → background.js**
     - **background.js → persistent storage**
     - **popup/settings UI → read aggregated state**
     - **popup/settings UI → write user preferences back**
   - This creates a clear separation between **event capture** and **presentation/configuration**.

7. **Persistence boundary**
   - Although not visible in the file list, a project like this almost certainly uses Chrome extension storage APIs for persistence.
   - That storage layer is the boundary between ephemeral runtime state and data that survives browser restarts.
   - Expect two categories of stored data: **tracked usage metrics** and **user preferences/filters**.

8. **Visualization subsystem**
   - The README mentions “data visualizations,” which suggests the settings or popup UI includes charts or summarized views.
   - That visualization layer is probably client-side only, rendering from aggregated tracking data produced by the background script.

9. **Filtering subsystem**
   - “Advanced filtering” implies the extension supports excluding or grouping certain tabs/sites, likely by hostname, URL pattern, or category.
   - Filtering is probably applied in the background tracker before metrics are finalized, and also exposed in settings for user control.

10. **Static assets and presentation**
   - `popup.css`, `settings.css`, and the `icons/` directory are purely presentation assets.
   - They don’t affect the data model, but they do define the extension’s browser action identity and the UI experience.

11. **No obvious backend dependency**
   - The repository contains only extension-side files and no server, database, or build pipeline.
   - Architecturally, this looks like a **self-contained local extension** with browser APIs as its only platform dependency.

12. **Diagram-friendly boundary summary**
   - The cleanest architecture diagram would show:
     - **Chrome browser events** feeding **background.js**
     - **background.js** persisting and aggregating tracking data
     - **popup UI** for quick status/actions
     - **settings UI** for filters, preferences, and visual summaries
     - **Chrome storage** as the shared persistence layer
     - **icons/assets** as static UI resources

Main entry points: [`background.js`](https://github.com/shubh-14-cloud/quantumtabs/blob/main/background.js) (Background), [`manifest.json`](https://github.com/shubh-14-cloud/quantumtabs/blob/main/manifest.json) (Manifest), [`popup.js`](https://github.com/shubh-14-cloud/quantumtabs/blob/main/popup.js) (Popup Logic), [`settings.js`](https://github.com/shubh-14-cloud/quantumtabs/blob/main/settings.js) (Settings Logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_extension["Extension shell"]
  node_manifest["Manifest<br/>[manifest.json]"]
  node_icons["Icons<br/>static assets"]
end

subgraph group_grp_core["Tracking core"]
  node_browser(("Browser events<br/>runtime events"))
  node_background["Background<br/>event tracker<br/>[background.js]"]
  node_filtering{{"Filtering<br/>rules engine"}}
  node_storage[("Storage<br/>persistent state")]
end

subgraph group_grp_ui["User interface"]
  node_popup_html["Popup UI<br/>entry view<br/>[popup.html]"]
  node_popup_js["Popup Logic<br/>ui controller<br/>[popup.js]"]
  node_popup_css["Popup Style<br/>presentation<br/>[popup.css]"]
  node_settings_html["Settings UI<br/>config view<br/>[settings.html]"]
  node_settings_js["Settings Logic<br/>ui controller<br/>[settings.js]"]
  node_settings_css["Settings Style<br/>presentation<br/>[settings.css]"]
end

node_manifest -->|"registers"| node_background
node_manifest -->|"opens"| node_popup_html
node_manifest -->|"opens"| node_settings_html
node_manifest -->|"uses"| node_icons
node_browser -->|"events"| node_background
node_background -->|"applies"| node_filtering
node_background -->|"persists"| node_storage
node_popup_js -->|"reads"| node_background
node_popup_js -->|"reads/writes"| node_storage
node_popup_html -->|"loads"| node_popup_js
node_popup_html -->|"styles"| node_popup_css
node_settings_js -->|"reads"| node_background
node_settings_js -->|"reads/writes"| node_storage
node_settings_html -->|"loads"| node_settings_js
node_settings_html -->|"styles"| node_settings_css
node_background -.->|"notifies"| node_popup_js
node_background -.->|"supplies"| node_settings_js

click node_manifest "https://github.com/shubh-14-cloud/quantumtabs/blob/main/manifest.json"
click node_icons "https://github.com/shubh-14-cloud/quantumtabs/tree/main/icons"
click node_background "https://github.com/shubh-14-cloud/quantumtabs/blob/main/background.js"
click node_popup_html "https://github.com/shubh-14-cloud/quantumtabs/blob/main/popup.html"
click node_popup_js "https://github.com/shubh-14-cloud/quantumtabs/blob/main/popup.js"
click node_popup_css "https://github.com/shubh-14-cloud/quantumtabs/blob/main/popup.css"
click node_settings_html "https://github.com/shubh-14-cloud/quantumtabs/blob/main/settings.html"
click node_settings_js "https://github.com/shubh-14-cloud/quantumtabs/blob/main/settings.js"
click node_settings_css "https://github.com/shubh-14-cloud/quantumtabs/blob/main/settings.css"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manifest,node_icons toneBlue
class node_browser,node_background,node_filtering,node_storage toneAmber
class node_popup_html,node_popup_js,node_popup_css,node_settings_html,node_settings_js,node_settings_css toneMint
```

## Components

### Extension shell

Manifest wiring and static extension assets.

- [Manifest](https://github.com/shubh-14-cloud/quantumtabs/blob/main/manifest.json): extension manifest · Top-level wiring for permissions, background execution, and UI entry points. · `manifest.json`
- [Icons](https://github.com/shubh-14-cloud/quantumtabs/tree/main/icons): static assets · Browser action and extension artwork. · `icons`

### Tracking core

Event capture, aggregation, filtering, and persistence boundary.

- **Browser events**: runtime events · Tab, window, and navigation events emitted by Chrome.
- [Background](https://github.com/shubh-14-cloud/quantumtabs/blob/main/background.js): event tracker · Central coordinator that observes activity and maintains usage state. · `background.js`
- **Filtering**: rules engine · Applies exclusion and grouping rules before metrics are finalized.
- **Storage**: persistent state · Shared browser storage for tracked usage and user preferences.

### User interface

Popup and settings surfaces for status, filters, and visualization.

- [Popup UI](https://github.com/shubh-14-cloud/quantumtabs/blob/main/popup.html): entry view · Primary lightweight extension popup surface. · `popup.html`
- [Popup Logic](https://github.com/shubh-14-cloud/quantumtabs/blob/main/popup.js): ui controller · Reads current state and drives quick actions in the popup. · `popup.js`
- [Popup Style](https://github.com/shubh-14-cloud/quantumtabs/blob/main/popup.css): presentation · Styling for the popup surface. · `popup.css`
- [Settings UI](https://github.com/shubh-14-cloud/quantumtabs/blob/main/settings.html): config view · Deeper configuration and visualization surface. · `settings.html`
- [Settings Logic](https://github.com/shubh-14-cloud/quantumtabs/blob/main/settings.js): ui controller · Loads aggregated data, manages preferences, and drives charts or summaries. · `settings.js`
- [Settings Style](https://github.com/shubh-14-cloud/quantumtabs/blob/main/settings.css): presentation · Styling for the settings surface. · `settings.css`

## Connections

- Manifest → Background: registers · Declares the background script as the extension runtime coordinator.
- Manifest → Popup UI: opens · Wires the browser action popup entry point.
- Manifest → Settings UI: opens · Wires the settings/options entry point.
- Manifest → Icons: uses · References icon assets for extension identity.
- Browser events → Background: events · Tab and navigation activity feeds the tracker.
- Background → Filtering: applies · Filters tracked activity before aggregation.
- Background → Storage: persists · Writes canonical usage data and state.
- Popup Logic → Background: reads · Fetches current tracker state for quick display.
- Popup Logic → Storage: reads/writes · Uses shared storage for user-visible state and preferences.
- Popup UI → Popup Logic: loads · Popup markup is driven by its controller script.
- Popup UI → Popup Style: styles · Popup layout and presentation are defined here.
- Settings Logic → Background: reads · Consumes aggregated tracking data from the core tracker.
- Settings Logic → Storage: reads/writes · Stores filters, preferences, and saved view state.
- Settings UI → Settings Logic: loads · Settings markup is driven by its controller script.
- Settings UI → Settings Style: styles · Settings layout and presentation are defined here.
- Background → Popup Logic: notifies · Supplies updated status to the popup surface.
- Background → Settings Logic: supplies · Provides aggregated usage data for visualization and configuration.
