Adhan Caster Pro — Architecture · System Design

🗺️ Layered map. Five layers: external services (amber), the popup UI (blue), the background service worker hub (green), the Chrome platform (violet), and content scripts in every tab (teal). Animated dashes show the live data channels. Click any node for its responsibility.

👆 Click a node to inspect itguide

Every box is a real file or Chrome API in the extension. The lines are message, storage and network channels — switch to the Workflow tab to watch data actually flow through them, step by step, during an Adhan event.

① Configure & Schedule

Step 1 / 11

Pick your location

—

📦 Manifest & permissions

manifestv3 · background type:module permissionsstorage · alarms · notifications · scripting · tabs hostapi.aladhan.com · http/https://* contentall frames · document_idle commandtoggle-focus → Ctrl/⌘+Shift+Y

🧱 Components

background.jsMV3 worker: fetch · alarms · notify · broadcast · auto-resume content.jsevery frame: 1 Hz tick · overlays (Shadow DOM) · pause/resume media popup.*prayer list · countdown · Resume · location search · settings lib/schedulepure: parse times · next prayer · stale-fire · format lib/geocodepure: Open-Meteo place search

⏰ Alarms

PRAYERadhan-prayer-fire — fires at next prayer ts RESUMEadhan-auto-resume — now + autoResumeMinutes TICKadhan-tick — every 15 min (self-heal)

Alarms re-armed on install, startup & each tick. isStaleFire() (≥90 s late) skips a slept-through Adhan.

💾 Storage schema chrome.storage.local

// settings — user config, merged over DEFAULT_SETTINGS
{ enabled, country, state, city, lat, lon,
  autoResumeMinutes:5, leadSeconds:30, focusMode:true }

// schedule — today's prayers (parsed to local-tz timestamps)
{ date:"YYYY-MM-DD", prayers:[{name,time,ts}…], fetchedAt }

// nextPrayer — the one alarm is armed for  (test:true on dev fires)
{ name, time, ts }

// paused — central cross-tab pause state
{ active, prayer, time, since, focus }

📡 Message catalog

GET_STATE · SAVE_SETTINGS · REFRESHpopup →read state / save+refetch / refetch

RESUME_NOW · FOCUS_NOWpopup / content →end pause · turn on focus

PRAYER_FALLBACKcontent →tab's own countdown hit 0 first

TEST_ADHANpopup →dev-only simulated Adhan (30s)

PRAYER_NOW · RESUMEbg ⇒ all tabspause everything · resume everything

FOCUS_ON · FOCUS_OFFbg ⇒ all tabsraise / drop focus overlay

🌐 External services

adhan-apiVercel — /api/prayerTimes → 5 daily times Open-Meteokeyless geocoding — city → region + coords

No backend of its own, no API keys, no runtime deps. The popup calls Open-Meteo directly; the worker calls adhan-api.

🛡️ Resilience patterns

Dual trigger — alarm and per-tab countdown both pause; idempotent.
Self-resume — content.js resumes if ALARM_RESUME never fires.
Reconcile — worker restart re-arms an in-progress pause.
Stale skip — slept-through Adhan is ignored, not replayed.
Single instance — token kills orphaned content scripts.
Re-prime tabs — inject into open tabs on install & startup.

🧪 Stack & quality

Vanilla JS ES modules Shadow DOM MV3 SW Jest unit tests Zero runtime deps

Pure logic in lib/ is unit-tested; manifest qualification tests gate every build.

Generated from source — background.js · content.js · popup.js · lib/ • Adhan Caster Pro v1.6.6 • single self-contained file