# mibrahimy/focusguard-extension architecture

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

- Interactive diagram: https://gitdiagram.com/mibrahimy/focusguard-extension
- Repository: https://github.com/mibrahimy/focusguard-extension

## Overview

##### Project type and purpose
- This is a browser extension (Chrome / Edge Manifest V3) called “FocusGuard.”
- Its goal is to intercept visits to specified websites, prompt the user for an intention, run a timed focus session, track and store session data, and display analytics in a dashboard.

##### File structure
- manifest.json: core extension configuration (permissions, entry points).
- background/service-worker.js: the persistent worker that listens for tab/navigation events, schedules reminders, processes messages, and interfaces with chrome.storage.
- content/: scripts injected into monitored pages to render the overlay UI (focus prompt, timer, reminders) and communicate with the background.
- popup/: UI for quick settings (select sites, view recent intentions, start session manually).
- dashboard/: full analytics interface (session history, charts, exports).

##### README for additional insights
- Uses Chrome Storage API (chrome.storage.local) for private, on-device data.
- Relies on chrome.tabs, chrome.activeTab, chrome.scripting to detect and inject content scripts.
- Provides dark/light theme support and local-only data export.

a. Main components
- Browser Host (Chrome/Edge)
- Manifest V3 → declares component entry points and permissions
- Background Service Worker (background/service-worker.js)
- Content Scripts (injected into monitored web pages)
- Popup UI (popup/popup.html + popup.js + popup.css)
- Dashboard UI (dashboard/dashboard.html + dashboard.js + dashboard.css)
- Local Storage (chrome.storage.local)
- External Website Domains (monitored sites)
b. Relationships & interactions
1. User navigates to a monitored site → Browser triggers background “onUpdated”/“onActivated” → background checks URL pattern.
2. If matched, background.injects content-script into page via chrome.scripting.
3. Content-script renders intention overlay and timer UI, sends “session-start” / “intent-selected” messages back to background.
4. Background persists session metadata in chrome.storage.local.
5. Content-script handles reminders and sends “session-end” / “session-pause” events to background.
6. Popup UI and Dashboard UI retrieve and update settings & analytics by querying background or directly reading chrome.storage.local.
c. Architectural patterns & design principles
- Event-driven messaging between background and UI/content scripts
- Single source of truth in chrome.storage.local for session and settings data
- Separation of concerns:
- Background: orchestration, storage, event handling
- Content: in-page UI, user interaction hooks
- Popup / Dashboard: configuration & analytics presentation
d. Key technologies/frameworks
- HTML/CSS/JS for UI
- Chrome Extension Manifest V3 (service worker model)
- chrome.storage API, chrome.tabs & chrome.scripting
- Optional charting library (e.g., Chart.js) in dashboard

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser["Browser Host (Chrome/Edge)"]:::manifest
    Manifest["manifest.json"]:::manifest
    Background["Background Service Worker"]:::background
    storage["Chrome Storage (local)"]:::storage
    Monitored["Monitored Websites"]:::external2

    subgraph "Frontend"
        direction TB
        subgraph "Content Scripts"
            direction TB
            CS1["content-script.js"]:::ui
            CS2["focusguard-content.js"]:::ui
        end
        subgraph "Popup UI"
            direction TB
            POPHTML["popup.html"]:::ui
            POPJS["popup.js"]:::ui
            POPCSS["popup.css"]:::ui
        end
        subgraph "Dashboard UI"
            direction TB
            DHTML["dashboard.html"]:::ui
            DJS["dashboard.js"]:::ui
            DCSS["dashboard.css"]:::ui
        end
    end

    subgraph "Shared Assets"
        direction TB
        A1["assets/css/content.css"]:::assets
        A2["assets/icons/"]:::assets
    end

    Browser --> Manifest
    Manifest --> Background
    Manifest --> CS1
    Manifest --> POPHTML
    Manifest --> DHTML

    Monitored -->|onUpdated/onActivated| Background
    Background -->|chrome.scripting.executeScript| CS1
    Background -->|chrome.scripting.executeScript| CS2
    CS1 -->|chrome.runtime.sendMessage| Background
    CS2 -->|chrome.runtime.sendMessage| Background

    Background -->|chrome.storage.set/get| storage
    POPJS -->|chrome.runtime.sendMessage| Background
    POPJS -->|chrome.storage.get/set| storage
    DJS -->|chrome.storage.get| storage
    DJS -->|chrome.runtime.sendMessage| Background

    A1 --> POPHTML
    A1 --> CS1
    A1 --> DHTML
    A2 --> POPHTML
    A2 --> CS1
    A2 --> DHTML

    click Manifest "https://github.com/mibrahimy/focusguard-extension/blob/main/manifest.json"
    click Background "https://github.com/mibrahimy/focusguard-extension/blob/main/background/service-worker.js"
    click CS1 "https://github.com/mibrahimy/focusguard-extension/blob/main/content/content-script.js"
    click CS2 "https://github.com/mibrahimy/focusguard-extension/blob/main/content/focusguard-content.js"
    click POPHTML "https://github.com/mibrahimy/focusguard-extension/blob/main/popup/popup.html"
    click POPJS "https://github.com/mibrahimy/focusguard-extension/blob/main/popup/popup.js"
    click POPCSS "https://github.com/mibrahimy/focusguard-extension/blob/main/popup/popup.css"
    click DHTML "https://github.com/mibrahimy/focusguard-extension/blob/main/dashboard/dashboard.html"
    click DJS "https://github.com/mibrahimy/focusguard-extension/blob/main/dashboard/dashboard.js"
    click DCSS "https://github.com/mibrahimy/focusguard-extension/blob/main/dashboard/dashboard.css"
    click A1 "https://github.com/mibrahimy/focusguard-extension/blob/main/assets/css/content.css"
    click A2 "https://github.com/mibrahimy/focusguard-extension/tree/main/assets/icons/"

    classDef manifest fill:#d9d9d9,stroke:#333
    classDef background fill:#cfe2f3,stroke:#2a6f97
    classDef ui fill:#d9ead3,stroke:#38761d
    classDef storage fill:#fff2cc,stroke:#e69138
    classDef external2 fill:#f9cb9c,stroke:#e06666
    classDef assets fill:#f4cccc,stroke:#b45f06
```
