# luaie/safeview architecture

> Architecture diagram of the GitHub repository luaie/safeview, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/luaie/safeview
- Repository: https://github.com/luaie/safeview

## Overview

SafeView is a browser extension that monitors video for rapid luminance changes and applies the user’s selected protection mode. The workflow runs from popup onboarding and settings, through frame sampling and flash detection, to a protection response; detected events are also reported to the extension background worker for badge and statistics updates. The README documents supported video sites and protection capabilities. Source excerpts show the sampler, detector, popup, and worker, but not how the page script is injected, so that handoff is marked unverified.

Main entry points: [`content.js`](https://github.com/luaie/safeview/blob/main/content.js) (Flash detector), [`popup.js`](https://github.com/luaie/safeview/blob/main/popup.js) (Settings and controls), [`background.js`](https://github.com/luaie/safeview/blob/main/background.js) (Background worker), [`popup.html`](https://github.com/luaie/safeview/blob/main/popup.html) (Popup interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_settings["Settings and UI"]
  node_popup_ui["Popup interface<br/>[popup.html]"]
  node_popup_logic["Settings and controls<br/>[popup.js]"]
end

subgraph group_monitor["Video monitoring"]
  node_sampler["Frame sampler<br/>[page-script.js]"]
  node_flash_detector["Flash detector<br/>[content.js]"]
end

subgraph group_protection["Protection responses"]
  node_protection_modes["Protection modes<br/>[content.js]"]
  node_warning_hud["Warnings and HUD<br/>[content.js]"]
end

subgraph group_extension["Extension services"]
  node_settings_store[("Synced settings")]
  node_background_worker["Background worker<br/>[background.js]"]
  node_badge["Browser action badge"]
end

node_user(("User"))
node_video_sites["Supported video sites"]

node_user -->|"configures"| node_popup_ui
node_popup_ui -->|"hosts controls"| node_popup_logic
node_popup_logic -->|"reads and writes"| node_settings_store
node_popup_logic -->|"pushes settings"| node_flash_detector
node_video_sites -->|"provides video"| node_sampler
node_sampler -.->|"posts luminance"| node_flash_detector
node_flash_detector -->|"loads settings"| node_settings_store
node_flash_detector -->|"triggers response"| node_protection_modes
node_protection_modes -->|"shows warnings"| node_warning_hud
node_flash_detector -->|"reports events"| node_background_worker
node_background_worker -->|"updates badge"| node_badge
node_popup_logic -->|"requests totals"| node_background_worker

click node_popup_ui "https://github.com/luaie/safeview/blob/main/popup.html"
click node_popup_logic "https://github.com/luaie/safeview/blob/main/popup.js"
click node_sampler "https://github.com/luaie/safeview/blob/main/page-script.js"
click node_flash_detector "https://github.com/luaie/safeview/blob/main/content.js"
click node_protection_modes "https://github.com/luaie/safeview/blob/main/content.js"
click node_warning_hud "https://github.com/luaie/safeview/blob/main/content.js"
click node_background_worker "https://github.com/luaie/safeview/blob/main/background.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_popup_ui,node_popup_logic,node_user toneBlue
class node_sampler,node_flash_detector toneAmber
class node_protection_modes,node_warning_hud toneMint
class node_settings_store,node_background_worker,node_badge toneRose
class node_video_sites toneIndigo
```

## Components

### Settings and UI

- [Popup interface](https://github.com/luaie/safeview/blob/main/popup.html): `popup.html`
- [Settings and controls](https://github.com/luaie/safeview/blob/main/popup.js): `popup.js`

### Video monitoring

- [Frame sampler](https://github.com/luaie/safeview/blob/main/page-script.js): `page-script.js`
- [Flash detector](https://github.com/luaie/safeview/blob/main/content.js): `content.js`

### Protection responses

- [Protection modes](https://github.com/luaie/safeview/blob/main/content.js): `content.js`
- [Warnings and HUD](https://github.com/luaie/safeview/blob/main/content.js): `content.js`

### Extension services

- **Synced settings**
- [Background worker](https://github.com/luaie/safeview/blob/main/background.js): `background.js`
- **Browser action badge**

### Other components

- **User**
- **Supported video sites**

## Connections

- User → Popup interface: configures (evidence: `README.md`)
- Popup interface → Settings and controls: hosts controls (evidence: `popup.js`)
- Settings and controls → Synced settings: reads and writes (evidence: `popup.js`)
- Settings and controls → Flash detector: pushes settings (evidence: `popup.js`)
- Supported video sites → Frame sampler: provides video (evidence: `README.md`)
- Frame sampler → Flash detector: posts luminance
- Flash detector → Synced settings: loads settings (evidence: `content.js`)
- Flash detector → Protection modes: triggers response (evidence: `content.js`)
- Protection modes → Warnings and HUD: shows warnings (evidence: `content.js`)
- Flash detector → Background worker: reports events (evidence: `content.js`)
- Background worker → Browser action badge: updates badge (evidence: `background.js`)
- Settings and controls → Background worker: requests totals (evidence: `popup.js`)
