# om-prakash-verma/snapsaver architecture

> Architecture diagram of the GitHub repository om-prakash-verma/snapsaver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/om-prakash-verma/snapsaver
- Repository: https://github.com/om-prakash-verma/snapsaver

## Overview

1. **What this repo is**
   SnapGallery is a Chrome Extension Manifest V3 project. Its architecture is split across three browser execution contexts: page-injected content scripts, a background service worker, and extension pages for the side panel downloader and options UI.

2. **Primary user-facing surface**
   The main product surface is the downloader side panel (`views/downloader.html` + `src/downloader/*`). This is where discovered media is listed, grouped, filtered, selected, and downloaded. The options page (`views/options.html` + `src/options/*`) is a separate configuration boundary for extension preferences.

3. **Page scraping boundary**
   All page inspection happens in `src/content-script/*`. This layer is responsible for extracting media from the active tab’s DOM and styles, including standard elements, CSS-driven assets, file-type detection, URL mapping, regex-based parsing, and media dispatch back to the extension UI. This code must operate inside the page context and stay isolated from extension-only APIs.

4. **Media discovery pipeline**
   The downloader-side logic in `src/downloader/find-media.ts` and related modules consumes media data coming from the content script, tracks it per tab, and coordinates refreshes when new content appears. The README’s focus on dynamic observation matches the architecture’s use of DOM mutation-driven scraping for SPA/infinite-scroll pages.

5. **Background orchestration**
   `src/background/background.ts` is the central extension coordinator. It likely handles lifecycle events, context menu actions, tab/side-panel wiring, and message routing between contexts. In MV3 terms, this is the place where browser-level events are converted into extension actions.

6. **Message-driven integration**
   Cross-context communication is explicit in the type layer (`src/types/message-event-name.enum.ts`, `tab-data.type.ts`, `found-media.type.ts`, etc.) and the listener modules (`src/downloader/message-listeners.ts`, `src/downloader/send-media-listener.ts`, `src/content-script/send_media.ts`). The architecture is event-driven rather than shared-memory based: page script extracts data, background relays/coordinates, side panel renders state.

7. **Media normalization and metadata**
   Several modules indicate a normalization stage before rendering: `mappers-fn.ts`, `extractors-fn.ts`, `filters-fn.ts`, `media-types.ts`, and `media-display.ts`. This is where raw page URLs become structured media records with consistent type, source, and display metadata suitable for grouping and filtering.

8. **Filtering subsystem**
   Filtering is a distinct subsystem in both the downloader UI and content processing layers. The UI-side filter modules under `src/downloader/filters/*` correspond to rendered controls, while the content-script-side filter helpers apply constraints to discovered media. The architecture keeps extraction separate from user filtering so the same media set can be re-rendered under different criteria without rescanning the page.

9. **Per-tab and persistent state**
   State is split between transient per-tab tracking (`src/media-in-tabs.ts`, `src/downloader/tab-info.ts`) and persistent extension storage (`src/storage/*`). `chrome.storage.sync` is used for durable settings and theme/preferences, while tab-scoped data keeps the downloader aligned with the active page and navigation changes.

10. **Download and file handling**
   Download-specific behavior lives in `src/utils/download-functions.ts` and related helpers. Supporting utilities like `crc32.ts` suggest deduplication or stable identity for assets, while `yt-restriction.ts` enforces special-case guardrails for restricted sites. This keeps policy checks and file transfer logic outside the rendering layer.

11. **UI composition**
   The downloader UI is modularized into accordion, filter, top-container, button, and info components under `src/downloader/*` and `css/downloader/*`. This points to a componentized, state-driven panel where media groups are expanded/collapsed, filtered, and acted on without page reloads.

12. **Options, theme, and presentation**
   Global appearance and preferences are centralized through `src/theme.ts`, `src/popup-dimensions.ts`, and `src/options/main.ts`, with corresponding CSS files for themes, radio/checkbox controls, and page-specific styling. Styling is separated from logic, and the options page is its own isolated settings surface.

13. **Shared platform utilities**
   Common browser and DOM abstractions live in `src/utils/*` and `src/types/*`. `chrome-api.ts` likely wraps extension API calls, while DOM helpers and shared types keep the background, content script, and UI layers aligned on contracts and reduce duplicated browser-specific code.

14. **Build and packaging boundary**
   Webpack and TypeScript are the build-time architecture layer (`webpack.config.js`, `tsconfig.json`, `package.json`). The repo ships as a compiled extension with HTML views, CSS assets, icons, and images, so the runtime application is assembled from multiple entry points rather than a single app bundle.

Main entry points: [`src/background/background.ts`](https://github.com/om-prakash-verma/snapsaver/blob/main/src/background/background.ts) (Background), [`webpack.config.js`](https://github.com/om-prakash-verma/snapsaver/blob/main/webpack.config.js) (Build config), [`src/content-script`](https://github.com/om-prakash-verma/snapsaver/tree/main/src/content-script) (Content script), [`src/downloader`](https://github.com/om-prakash-verma/snapsaver/tree/main/src/downloader) (Downloader UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Browser runtime"]
  node_bg["Background<br/>service worker<br/>[background.ts]"]
  node_content["Content script<br/>page scraper"]
  node_downloader["Downloader UI<br/>side panel"]
  node_options["Options UI<br/>settings page<br/>[main.ts]"]
  node_views["HTML views<br/>entry pages"]
  node_extract["Extractors<br/>media scan<br/>[extractors-fn.ts]"]
  node_map["Mappers<br/>normalizer<br/>[mappers-fn.ts]"]
  node_cfilters["Page filters<br/>scrape filter<br/>[filters-fn.ts]"]
  node_send["Send media<br/>message emitter<br/>[send_media.ts]"]
  node_find["Find media<br/>tab tracker<br/>[find-media.ts]"]
  node_listeners["Message listeners<br/>event bridge"]
  node_filters["UI filters<br/>filtering"]
  node_accordion["Media groups<br/>ui component<br/>[accordion.ts]"]
end

subgraph group_data["Data model"]
  node_storage[("Storage<br/>persistent state")]
  node_tabstate[("Tab state<br/>transient state<br/>[media-in-tabs.ts]")]
  node_types["Shared types<br/>contracts"]
  node_media["Media model<br/>normalize layer<br/>[media-types.ts]"]
  node_utils["Utilities<br/>helpers"]
end

subgraph group_build["Build"]
  node_build["Build config<br/>packaging<br/>[webpack.config.js]"]
end

node_content -->|"scans"| node_extract
node_extract -->|"normalizes"| node_map
node_map -->|"classifies"| node_cfilters
node_content -->|"dispatches"| node_send
node_send -->|"messages"| node_bg
node_bg -->|"routes"| node_listeners
node_listeners -->|"updates"| node_find
node_find -->|"renders"| node_accordion
node_find -->|"filters"| node_filters
node_filters -->|"refines"| node_accordion
node_bg -->|"reads/writes"| node_storage
node_downloader -->|"tracks"| node_tabstate
node_content -->|"shares contracts"| node_types
node_downloader -->|"formats"| node_media
node_options -->|"configures"| node_storage
node_utils -.->|"supports"| node_bg
node_views -->|"hosts"| node_downloader
node_views -->|"hosts"| node_options
node_build -.->|"bundles"| node_bg
node_build -.->|"bundles"| node_content
node_build -.->|"bundles"| node_downloader
node_build -.->|"bundles"| node_options

click node_bg "https://github.com/om-prakash-verma/snapsaver/blob/main/src/background/background.ts"
click node_content "https://github.com/om-prakash-verma/snapsaver/tree/main/src/content-script"
click node_downloader "https://github.com/om-prakash-verma/snapsaver/tree/main/src/downloader"
click node_options "https://github.com/om-prakash-verma/snapsaver/blob/main/src/options/main.ts"
click node_views "https://github.com/om-prakash-verma/snapsaver/tree/main/views"
click node_extract "https://github.com/om-prakash-verma/snapsaver/blob/main/src/content-script/extractors-fn.ts"
click node_map "https://github.com/om-prakash-verma/snapsaver/blob/main/src/content-script/mappers-fn.ts"
click node_cfilters "https://github.com/om-prakash-verma/snapsaver/blob/main/src/content-script/filters-fn.ts"
click node_send "https://github.com/om-prakash-verma/snapsaver/blob/main/src/content-script/send_media.ts"
click node_find "https://github.com/om-prakash-verma/snapsaver/blob/main/src/downloader/find-media.ts"
click node_listeners "https://github.com/om-prakash-verma/snapsaver/blob/main/src/downloader/message-listeners.ts"
click node_filters "https://github.com/om-prakash-verma/snapsaver/tree/main/src/downloader/filters"
click node_accordion "https://github.com/om-prakash-verma/snapsaver/blob/main/src/downloader/accordion.ts"
click node_storage "https://github.com/om-prakash-verma/snapsaver/tree/main/src/storage"
click node_tabstate "https://github.com/om-prakash-verma/snapsaver/blob/main/src/media-in-tabs.ts"
click node_types "https://github.com/om-prakash-verma/snapsaver/tree/main/src/types"
click node_media "https://github.com/om-prakash-verma/snapsaver/blob/main/src/downloader/media-types.ts"
click node_utils "https://github.com/om-prakash-verma/snapsaver/tree/main/src/utils"
click node_build "https://github.com/om-prakash-verma/snapsaver/blob/main/webpack.config.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_bg,node_content,node_downloader,node_options,node_views,node_extract,node_map,node_cfilters,node_send,node_find,node_listeners,node_filters,node_accordion toneBlue
class node_storage,node_tabstate,node_types,node_media,node_utils toneAmber
class node_build toneMint
```

## Components

### Browser runtime

Extension execution contexts and user-facing surfaces.

- [Background](https://github.com/om-prakash-verma/snapsaver/blob/main/src/background/background.ts): service worker · Central MV3 coordinator for lifecycle, routing, and extension events. · `src/background/background.ts`
- [Content script](https://github.com/om-prakash-verma/snapsaver/tree/main/src/content-script): page scraper · Runs in page context to inspect DOM, styles, and visible media. · `src/content-script`
- [Downloader UI](https://github.com/om-prakash-verma/snapsaver/tree/main/src/downloader): side panel · Main discovery, grouping, filtering, and download interface. · `src/downloader`
- [Options UI](https://github.com/om-prakash-verma/snapsaver/blob/main/src/options/main.ts): settings page · Extension preferences and appearance configuration surface. · `src/options/main.ts`
- [HTML views](https://github.com/om-prakash-verma/snapsaver/tree/main/views): entry pages · Extension pages that mount the downloader, options, and changelog surfaces. · `views`
- [Extractors](https://github.com/om-prakash-verma/snapsaver/blob/main/src/content-script/extractors-fn.ts): media scan · Finds standard elements and CSS-driven assets from the active page. · `src/content-script/extractors-fn.ts`
- [Mappers](https://github.com/om-prakash-verma/snapsaver/blob/main/src/content-script/mappers-fn.ts): normalizer · Converts raw page URLs and attributes into structured media records. · `src/content-script/mappers-fn.ts`
- [Page filters](https://github.com/om-prakash-verma/snapsaver/blob/main/src/content-script/filters-fn.ts): scrape filter · Applies page-side constraints and regex-based matching during discovery. · `src/content-script/filters-fn.ts`
- [Send media](https://github.com/om-prakash-verma/snapsaver/blob/main/src/content-script/send_media.ts): message emitter · Dispatches discovered media from the page context to extension listeners. · `src/content-script/send_media.ts`
- [Find media](https://github.com/om-prakash-verma/snapsaver/blob/main/src/downloader/find-media.ts): tab tracker · Tracks discovered media per tab and coordinates refreshes in the downloader. · `src/downloader/find-media.ts`
- [Message listeners](https://github.com/om-prakash-verma/snapsaver/blob/main/src/downloader/message-listeners.ts): event bridge · Receives and interprets extension messages for the downloader state flow. · `src/downloader/message-listeners.ts`
- [UI filters](https://github.com/om-prakash-verma/snapsaver/tree/main/src/downloader/filters): filtering · Downloader-side filter controls and selection logic for the rendered media set. · `src/downloader/filters`
- [Media groups](https://github.com/om-prakash-verma/snapsaver/blob/main/src/downloader/accordion.ts): ui component · Renders grouped, collapsible media results with thumbnails and controls. · `src/downloader/accordion.ts`

### Data model

Shared types, state, and normalization boundaries.

- [Storage](https://github.com/om-prakash-verma/snapsaver/tree/main/src/storage): persistent state · Wraps durable settings and sync-backed extension preferences. · `src/storage`
- [Tab state](https://github.com/om-prakash-verma/snapsaver/blob/main/src/media-in-tabs.ts): transient state · Keeps per-tab discovery and active-page context aligned. · `src/media-in-tabs.ts`
- [Shared types](https://github.com/om-prakash-verma/snapsaver/tree/main/src/types): contracts · Message names, found-media records, tab data, and shared extension contracts. · `src/types`
- [Media model](https://github.com/om-prakash-verma/snapsaver/blob/main/src/downloader/media-types.ts): normalize layer · Shared media metadata, display, and file-type classification logic. · `src/downloader/media-types.ts`
- [Utilities](https://github.com/om-prakash-verma/snapsaver/tree/main/src/utils): helpers · Chrome API wrapper, DOM helpers, download logic, CRC, and site restrictions. · `src/utils`

### Build

Packaging and compile-time structure.

- [Build config](https://github.com/om-prakash-verma/snapsaver/blob/main/webpack.config.js): packaging · TypeScript and Webpack compile the multi-entry extension bundle. · `webpack.config.js`

## Connections

- Content script → Extractors: scans · Page context locates candidate media from DOM and styles.
- Extractors → Mappers: normalizes · Raw assets are converted into structured media records.
- Mappers → Page filters: classifies · Regex and type rules refine discovered media during scraping.
- Content script → Send media: dispatches · Scraped media is sent back to extension listeners.
- Send media → Background: messages · Cross-context events reach the background coordinator.
- Background → Message listeners: routes · Background events are forwarded into downloader state handling.
- Message listeners → Find media: updates · Incoming media updates per-tab discovery state.
- Find media → Media groups: renders · Tracked media is grouped for the side panel UI.
- Find media → UI filters: filters · UI filtering changes the visible media set.
- UI filters → Media groups: refines · Filtered results are presented as collapsible groups.
- Background → Storage: reads/writes · Extension lifecycle and preferences use durable storage.
- Downloader UI → Tab state: tracks · Downloader keeps per-tab discovery aligned with navigation.
- Content script → Shared types: shares contracts · Message and media schemas align page and extension contexts.
- Downloader UI → Media model: formats · Downloader presentation uses shared media metadata and display rules.
- Options UI → Storage: configures · Settings UI persists user preferences and theme state.
- Utilities → Background: supports · Common wrappers and helpers back background orchestration.
- HTML views → Downloader UI: hosts · Downloader HTML mounts the side panel application.
- HTML views → Options UI: hosts · Options HTML mounts the settings application.
- Build config → Background: bundles · Webpack/TypeScript produce the service worker entry.
- Build config → Content script: bundles · Webpack/TypeScript produce the page-injected script.
- Build config → Downloader UI: bundles · Webpack/TypeScript produce the side panel UI.
- Build config → Options UI: bundles · Webpack/TypeScript produce the options page.
