# sserdardundar/github-smart-downloader architecture

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

- Interactive diagram: https://gitdiagram.com/sserdardundar/github-smart-downloader
- Repository: https://github.com/sserdardundar/github-smart-downloader

## Overview

GitHub Smart Downloader is a Chrome extension that turns a repository, folder, or selected files into a ZIP. Users start from GitHub’s injected controls or the popup, choose a branch or selection, and the background worker coordinates a download job. The offscreen engine fetches or reuses repository data, applies filters or selections, and builds the archive before the browser downloads it; progress is shown in the UI. The README documents these capabilities; sampled excerpts do not expose every message handler, so uncertain links are omitted.

Main entry points: [`js/background.js`](https://github.com/sserdardundar/github-smart-downloader/blob/main/js/background.js) (Background Worker), [`js/offscreen.js`](https://github.com/sserdardundar/github-smart-downloader/blob/main/js/offscreen.js) (Offscreen Processor), [`js/popup.js`](https://github.com/sserdardundar/github-smart-downloader/blob/main/js/popup.js) (Popup and Branch Picker), [`js/contentScript.js`](https://github.com/sserdardundar/github-smart-downloader/blob/main/js/contentScript.js) (GitHub Page Controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User Interfaces"]
  node_content["GitHub Page Controls<br/>[contentScript.js]"]
  node_popup["Popup and Branch Picker<br/>[popup.js]"]
end

subgraph group_jobs["Download Coordination"]
  node_background["Background Worker<br/>[background.js]"]
  node_shared["Shared Parsing and Planning<br/>[shared.js]"]
end

subgraph group_engine["Archive Engine"]
  node_offscreen["Offscreen Processor<br/>[offscreen.js]"]
  node_enumerate["Repository Enumeration<br/>[offscreen.js]"]
  node_selection["Selection and Exclusions<br/>[offscreen.js]"]
  node_archive["Archive Fetch and Extraction<br/>[offscreen.js]"]
  node_cache[("Shared Archive Cache<br/>[offscreen.js]")]
  node_zip["ZIP Generation<br/>[offscreen.js]"]
  node_indexeddb[("IndexedDB Archive Store<br/>[offscreen.js]")]
end

subgraph group_prefs["Settings and State"]
  node_settings["Preferences UI<br/>[settings.js]"]
  node_storage[("Extension Storage")]
end

node_user(("User"))
node_github{{"GitHub API and Content"}}
node_browser["Browser Downloads"]

node_user -->|"select items"| node_content
node_user -->|"start download"| node_popup
node_user -->|"configure"| node_settings
node_content -->|"submit job"| node_background
node_popup -->|"submit job"| node_background
node_popup -->|"fetch branches"| node_github
node_background -->|"plan strategy"| node_shared
node_background -->|"delegate job"| node_offscreen
node_offscreen -->|"enumerate files"| node_enumerate
node_offscreen -->|"expand and filter"| node_selection
node_offscreen -->|"fetch archive"| node_archive
node_enumerate -->|"request tree"| node_github
node_archive -->|"fetch repository data"| node_github
node_archive -->|"reuse or store"| node_cache
node_archive -->|"read or write"| node_indexeddb
node_offscreen -->|"generate ZIP"| node_zip
node_background -->|"start download"| node_browser
node_background -->|"send progress"| node_content
node_background -->|"send progress"| node_popup
node_content -->|"read preferences"| node_storage
node_popup -->|"read and write"| node_storage
node_settings -->|"read and write"| node_storage
node_background -->|"persist job data"| node_storage

click node_content "https://github.com/sserdardundar/github-smart-downloader/blob/main/js/contentScript.js"
click node_popup "https://github.com/sserdardundar/github-smart-downloader/blob/main/js/popup.js"
click node_settings "https://github.com/sserdardundar/github-smart-downloader/blob/main/js/settings.js"
click node_background "https://github.com/sserdardundar/github-smart-downloader/blob/main/js/background.js"
click node_shared "https://github.com/sserdardundar/github-smart-downloader/blob/main/js/shared.js"
click node_offscreen "https://github.com/sserdardundar/github-smart-downloader/blob/main/js/offscreen.js"
click node_enumerate "https://github.com/sserdardundar/github-smart-downloader/blob/main/js/offscreen.js"
click node_selection "https://github.com/sserdardundar/github-smart-downloader/blob/main/js/offscreen.js"
click node_archive "https://github.com/sserdardundar/github-smart-downloader/blob/main/js/offscreen.js"
click node_cache "https://github.com/sserdardundar/github-smart-downloader/blob/main/js/offscreen.js"
click node_zip "https://github.com/sserdardundar/github-smart-downloader/blob/main/js/offscreen.js"
click node_indexeddb "https://github.com/sserdardundar/github-smart-downloader/blob/main/js/offscreen.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_content,node_popup,node_user,node_browser toneBlue
class node_background,node_shared toneAmber
class node_offscreen,node_enumerate,node_selection,node_archive,node_cache,node_zip,node_indexeddb,node_github toneMint
class node_settings,node_storage toneRose
```

## Components

### User Interfaces

- [GitHub Page Controls](https://github.com/sserdardundar/github-smart-downloader/blob/main/js/contentScript.js): `js/contentScript.js`
- [Popup and Branch Picker](https://github.com/sserdardundar/github-smart-downloader/blob/main/js/popup.js): `js/popup.js`

### Download Coordination

- [Background Worker](https://github.com/sserdardundar/github-smart-downloader/blob/main/js/background.js): `js/background.js`
- [Shared Parsing and Planning](https://github.com/sserdardundar/github-smart-downloader/blob/main/js/shared.js): `js/shared.js`

### Archive Engine

- [Offscreen Processor](https://github.com/sserdardundar/github-smart-downloader/blob/main/js/offscreen.js): `js/offscreen.js`
- [Repository Enumeration](https://github.com/sserdardundar/github-smart-downloader/blob/main/js/offscreen.js): `js/offscreen.js`
- [Selection and Exclusions](https://github.com/sserdardundar/github-smart-downloader/blob/main/js/offscreen.js): `js/offscreen.js`
- [Archive Fetch and Extraction](https://github.com/sserdardundar/github-smart-downloader/blob/main/js/offscreen.js): `js/offscreen.js`
- [Shared Archive Cache](https://github.com/sserdardundar/github-smart-downloader/blob/main/js/offscreen.js): `js/offscreen.js`
- [ZIP Generation](https://github.com/sserdardundar/github-smart-downloader/blob/main/js/offscreen.js): `js/offscreen.js`
- [IndexedDB Archive Store](https://github.com/sserdardundar/github-smart-downloader/blob/main/js/offscreen.js): `js/offscreen.js`

### Settings and State

- [Preferences UI](https://github.com/sserdardundar/github-smart-downloader/blob/main/js/settings.js): `js/settings.js`
- **Extension Storage**

### Other components

- **User**
- **GitHub API and Content**
- **Browser Downloads**

## Connections

- User → GitHub Page Controls: select items
- User → Popup and Branch Picker: start download
- User → Preferences UI: configure
- GitHub Page Controls → Background Worker: submit job
- Popup and Branch Picker → Background Worker: submit job
- Popup and Branch Picker → GitHub API and Content: fetch branches
- Background Worker → Shared Parsing and Planning: plan strategy
- Background Worker → Offscreen Processor: delegate job
- Offscreen Processor → Repository Enumeration: enumerate files
- Offscreen Processor → Selection and Exclusions: expand and filter
- Offscreen Processor → Archive Fetch and Extraction: fetch archive
- Repository Enumeration → GitHub API and Content: request tree
- Archive Fetch and Extraction → GitHub API and Content: fetch repository data
- Archive Fetch and Extraction → Shared Archive Cache: reuse or store
- Archive Fetch and Extraction → IndexedDB Archive Store: read or write
- Offscreen Processor → ZIP Generation: generate ZIP
- Background Worker → Browser Downloads: start download
- Background Worker → GitHub Page Controls: send progress
- Background Worker → Popup and Branch Picker: send progress
- GitHub Page Controls → Extension Storage: read preferences
- Popup and Branch Picker → Extension Storage: read and write
- Preferences UI → Extension Storage: read and write
- Background Worker → Extension Storage: persist job data