How shubh-14-cloud/quantumtabs works
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 Background · manifest.json Manifest · popup.js Popup Logic · settings.js Settings Logic
Components 12
Extension shell
Manifest wiring and static extension assets.
Tracking core
Event capture, aggregation, filtering, and persistence boundary.
- Browser events · Tab, window, and navigation events emitted by Chrome.
- Background · Central coordinator that observes activity and maintains usage state.
background.js - Filtering · Applies exclusion and grouping rules before metrics are finalized.
- Storage · Shared browser storage for tracked usage and user preferences.
User interface
Popup and settings surfaces for status, filters, and visualization.
- Popup UI · Primary lightweight extension popup surface.
popup.html - Popup Logic · Reads current state and drives quick actions in the popup.
popup.js - Popup Style · Styling for the popup surface.
popup.css - Settings UI · Deeper configuration and visualization surface.
settings.html - Settings Logic · Loads aggregated data, manages preferences, and drives charts or summaries.
settings.js - Settings Style · Styling for the settings surface.
settings.css
Connections 17
- 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.