How avpxm8/focus-tunnel works
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.