Architecture

How the service worker, content scripts and storage fit together.

Source · docs/ARCHITECTURE.md

FocusTube follows the standard Manifest V3 separation: one background service worker owns timers and messaging, content scripts do page-level work, and chrome.storage.local is the single source of truth shared between them.

┌──────────────────────────────┐
│  Background service worker   │
│  timers · messages · sync    │
└──────────────┬───────────────┘
               ↕ chrome.storage.local
┌──────────────┴───────────────┐
│  Content scripts             │
│  core/     storage wrapper,  │
│            logger, DOM utils │
│  blocking/ site · ads ·      │
│            shorts · keyword  │
│  youtube/  autoplay · quality│
│            watch-intent      │
│  ui/       orchestrator      │
└──────────────────────────────┘

text

Data flow — blocking a site

The popup writes to blockedSites in storage; the background updates declarativeNetRequest rules; the site blocker in each tab listens for the change and shows the interstitial if you're already there. One source of truth, three consumers.

Design system

Every surface — popup, dashboard, overlays, block page, digest, onboarding — consumes the same tokens from src/shared/apple-ui.css and liquid-glass.css: SF Pro / SF Mono type ramps, inset-grouped cards, semantic iOS colors and spring easing, with full prefers-reduced-motion support.