# avpxm8/focus-tunnel architecture

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

- Interactive diagram: https://gitdiagram.com/avpxm8/focus-tunnel
- Repository: https://github.com/avpxm8/focus-tunnel

## Overview

##### Project Type and Purpose
- Focus Tunnel is a Chrome Extension (Manifest V3) designed to help users enter deep-work sessions by providing a Pomodoro timer and blocking distracting websites.
- It’s purely client-side; there is no external server. All state is stored via Chrome’s storage APIs, and all blocking is done with Chrome’s declarativeNetRequest.

##### File Structure
- background.js: The service worker that handles alarms, timer logic, dynamic rule updates for blocking, and notifications.
- popup.html / popup.css / popup.js: The browser-toolbar UI where the user enters blocklist sites, configures timer durations, and starts/stops sessions.
- blocked.html / blocked.css: The “block page” shown in place of any blocked site during an active session.
- .gitignore, Readme.md: Project documentation and ignore rules.

##### Extract Architecture Insights from the README
- Core features use these Chrome APIs: storage (settings + blocklist persistence), alarms (Pomodoro timer), declarativeNetRequest (site blocking), notifications (session-end alerts).
- The extension follows an event-driven pattern: user actions in popup → background scripts react → Chrome APIs enforce behavior.

##### Main Components
a. UI Layer (Popup)
- popup.html/js/css
- Responsibilities: collect user input (blocklist, durations), send commands to background service worker.
b. Background Service Worker
- background.js
- Responsibilities: schedule/handle alarms, update blocking rules in declarativeNetRequest, manage timer state, send notifications.
c. Chrome Storage
- chrome.storage.sync or local
- Responsibilities: persist blocklist, session state, last timer value for session persistence.
d. Site Blocking Engine
- Chrome declarativeNetRequest
- Responsibilities: apply/remove URL-blocking rules dynamically based on session state.
e. Block Page
- blocked.html/css
- Responsibilities: display motivational message when user tries to access blocked URL.
f. Chrome Notifications
- For end-of-session alerts.

##### Relationships & Data Flow
2. Popup → reads/writes settings in Chrome Storage.
3. User clicks “Start” → popup sends message (chrome.runtime.sendMessage) to Service Worker.
4. Service Worker →
- sets an alarm via chrome.alarms.create for Pomodoro end,
- installs declarativeNetRequest block rules,
5. Browser navigation requests → checked by declarativeNetRequest → if matched, redirect to blocked.html.
6. Alarm fires → Service Worker → clears block rules, sends chrome.notifications to user, resets badge.

##### Architectural Patterns & Principles
- Event-Driven: All actions originate from Chrome events (UI clicks, alarms, network requests).
- Separation of Concerns:
- UI (popup) only handles input/output,
- Service Worker centralizes session logic,
- Storage persists data,
- declarativeNetRequest enforces blocking.
- Declarative API Usage: No manual request interception; reliant on the high-performance rule engine.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "Popup UI" 
        direction TB
        popup_html["popup.html"]:::frontend
        popup_js["popup.js"]:::frontend
        popup_css["popup.css"]:::frontend
    end

    %% Background Layer
    subgraph "Background Service Worker"
        direction TB
        bg["background.js"]:::backend
    end

    %% Configuration
    manifest["manifest.json"]:::config

    %% Storage
    storage["Chrome Storage"]:::storage

    %% Blocking Engine
    blockengine["Site Blocking Engine\n(declarativeNetRequest)"]:::api

    %% Block Page
    subgraph "Block Page"
        direction TB
        blocked_html["blocked.html"]:::block
        blocked_css["blocked.css"]:::block
    end

    %% Notifications
    notifications["Chrome Notifications"]:::api

    %% Assets & Docs
    icons["icons/"]:::assets
    readme["Readme.md"]:::docs
    gitignore[".gitignore"]:::docs

    %% Connections
    popup_html -->|"loads UI"| popup_js
    popup_js -->|"applies styles"| popup_css

    popup_js -->|"read/write settings"| storage
    popup_js -->|"sendMessage: start/stop"| bg

    bg <-->|"read/write state"| storage
    bg -->|"install/remove rules"| blockengine
    blockengine -->|"redirect"| blocked_html
    blockengine -->|"redirect"| blocked_css
    bg -->|"send notification"| notifications

    manifest -->|"defines UI & permissions"| popup_html
    manifest -->|"defines SW & rules"| bg

    %% External Assets & Docs
    manifest ---> icons
    manifest --- readme
    manifest --- gitignore

    %% Click Events
    click popup_html "https://github.com/avpxm8/focus-tunnel/blob/main/popup.html"
    click popup_js "https://github.com/avpxm8/focus-tunnel/blob/main/popup.js"
    click popup_css "https://github.com/avpxm8/focus-tunnel/blob/main/popup.css"
    click bg "https://github.com/avpxm8/focus-tunnel/blob/main/background.js"
    click manifest "https://github.com/avpxm8/focus-tunnel/blob/main/manifest.json"
    click blocked_html "https://github.com/avpxm8/focus-tunnel/blob/main/blocked.html"
    click blocked_css "https://github.com/avpxm8/focus-tunnel/blob/main/blocked.css"
    click icons "https://github.com/avpxm8/focus-tunnel/tree/main/icons/"
    click readme "https://github.com/avpxm8/focus-tunnel/blob/main/Readme.md"
    click gitignore "https://github.com/avpxm8/focus-tunnel/blob/main/.gitignore"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#2C7BE5,color:#052C65;
    classDef backend fill:#E6F6D0,stroke:#7BB828,color:#3B4F20;
    classDef storage fill:#FFF4D6,stroke:#E6A300,color:#5C4300,shape:cylinder;
    classDef api fill:#FFE6D8,stroke:#FF7F11,color:#662E00;
    classDef block fill:#FFDCE0,stroke:#E5534B,color:#5D1F1C;
    classDef config fill:#F0F0F0,stroke:#888888,color:#333333;
    classDef assets fill:#F5EEFF,stroke:#A163D0,color:#32145A;
    classDef docs fill:#E8F0FE,stroke:#4285F4,color:#1A73E8;
    classDef external stroke-dasharray: 5 5;color:#666666;
```
