# rapabru/github-download-button architecture

> Architecture diagram of the GitHub repository rapabru/github-download-button, 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/rapabru/github-download-button
- Repository: https://github.com/rapabru/github-download-button
- Video tour (about a minute): https://gitdiagram.com/rapabru/github-download-button/video

## Overview

This Chromium extension adds repository-aware download controls to GitHub pages. Its main workflow detects a repository, resolves the current or chosen ref, presents download choices, and delegates downloads to the service worker; the “files only” option additionally repackages an archive in an offscreen document. The README documents branch and release listings, private-repository fallbacks, and SPA resynchronization. Some source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`content.js`](https://github.com/rapabru/github-download-button/blob/main/content.js) (Detection and UI), [`background.js`](https://github.com/rapabru/github-download-button/blob/main/background.js) (Download service worker), [`offscreen.js`](https://github.com/rapabru/github-download-button/blob/main/offscreen.js) (Archive fetch and filtering), [`styles.css`](https://github.com/rapabru/github-download-button/blob/main/styles.css) (Button and popover styles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_page["GitHub page experience"]
  node_content["Detection and UI<br/>[content.js]"]
  node_styles["Button and popover styles<br/>[styles.css]"]
end

subgraph group_discovery["Repository discovery"]
  node_repo_state["Repo and ref resolution<br/>[content.js]"]
  node_branch_listing["Branch listing<br/>[content.js]"]
  node_release_listing["Release listing<br/>[content.js]"]
end

subgraph group_downloads["Download handling"]
  node_service_worker["Download service worker<br/>[background.js]"]
end

subgraph group_repack["ZIP repackaging"]
  node_offscreen_doc["Offscreen document<br/>[offscreen.html]"]
  node_offscreen["Archive fetch and filtering<br/>[offscreen.js]"]
  node_zip["ZIP reader and writer<br/>[zip.js]"]
end

node_user(("GitHub visitor"))
node_repo_page(("Repository page"))
node_github_internal["GitHub refs endpoint"]
node_github_api["GitHub REST API"]
node_archive["Repository archive"]
node_browser_downloads["Browser downloads"]

node_user -->|"uses controls"| node_content
node_repo_page -->|"provides page"| node_content
node_content -->|"uses styles"| node_styles
node_content -->|"detects and resolves"| node_repo_state
node_content -->|"requests branches"| node_branch_listing
node_content -->|"requests releases"| node_release_listing
node_branch_listing -->|"fetches refs"| node_github_internal
node_release_listing -.->|"falls back to tags"| node_github_internal
node_branch_listing -.->|"falls back to API"| node_content
node_release_listing -.->|"falls back to API"| node_content
node_content -->|"sends messages"| node_service_worker
node_service_worker -->|"fetches API"| node_github_api
node_content -->|"requests download"| node_service_worker
node_service_worker -->|"probes URL"| node_archive
node_service_worker -->|"starts download"| node_browser_downloads
node_content -->|"requests repack"| node_service_worker
node_service_worker -->|"creates document"| node_offscreen_doc
node_service_worker -->|"dispatches repack"| node_offscreen
node_offscreen -->|"fetches ZIP"| node_archive
node_offscreen -->|"reads and builds"| node_zip
node_offscreen -->|"returns blob URL"| node_service_worker
node_service_worker -->|"downloads repacked ZIP"| node_browser_downloads
node_service_worker -->|"reports progress"| node_content

click node_content "https://github.com/rapabru/github-download-button/blob/main/content.js"
click node_styles "https://github.com/rapabru/github-download-button/blob/main/styles.css"
click node_repo_state "https://github.com/rapabru/github-download-button/blob/main/content.js"
click node_branch_listing "https://github.com/rapabru/github-download-button/blob/main/content.js"
click node_release_listing "https://github.com/rapabru/github-download-button/blob/main/content.js"
click node_service_worker "https://github.com/rapabru/github-download-button/blob/main/background.js"
click node_offscreen_doc "https://github.com/rapabru/github-download-button/blob/main/offscreen.html"
click node_offscreen "https://github.com/rapabru/github-download-button/blob/main/offscreen.js"
click node_zip "https://github.com/rapabru/github-download-button/blob/main/zip.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_styles,node_browser_downloads toneBlue
class node_repo_state,node_branch_listing,node_release_listing toneAmber
class node_service_worker,node_github_api toneMint
class node_offscreen_doc,node_offscreen,node_zip toneRose
class node_user,node_repo_page,node_github_internal,node_archive toneIndigo
```

## Components

### GitHub page experience

- [Detection and UI](https://github.com/rapabru/github-download-button/blob/main/content.js): `content.js`
- [Button and popover styles](https://github.com/rapabru/github-download-button/blob/main/styles.css): `styles.css`

### Repository discovery

- [Repo and ref resolution](https://github.com/rapabru/github-download-button/blob/main/content.js): `content.js`
- [Branch listing](https://github.com/rapabru/github-download-button/blob/main/content.js): `content.js`
- [Release listing](https://github.com/rapabru/github-download-button/blob/main/content.js): `content.js`

### Download handling

- [Download service worker](https://github.com/rapabru/github-download-button/blob/main/background.js): `background.js`

### ZIP repackaging

- [Offscreen document](https://github.com/rapabru/github-download-button/blob/main/offscreen.html): `offscreen.html`
- [Archive fetch and filtering](https://github.com/rapabru/github-download-button/blob/main/offscreen.js): `offscreen.js`
- [ZIP reader and writer](https://github.com/rapabru/github-download-button/blob/main/zip.js): `zip.js`

### Other components

- **GitHub visitor**
- **Repository page**
- **GitHub refs endpoint**
- **GitHub REST API**
- **Repository archive**
- **Browser downloads**

## Connections

- GitHub visitor → Detection and UI: uses controls
- Repository page → Detection and UI: provides page
- Detection and UI → Button and popover styles: uses styles
- Detection and UI → Repo and ref resolution: detects and resolves
- Detection and UI → Branch listing: requests branches
- Detection and UI → Release listing: requests releases
- Branch listing → GitHub refs endpoint: fetches refs
- Release listing → GitHub refs endpoint: falls back to tags
- Branch listing → Detection and UI: falls back to API
- Release listing → Detection and UI: falls back to API
- Detection and UI → Download service worker: sends messages
- Download service worker → GitHub REST API: fetches API
- Detection and UI → Download service worker: requests download
- Download service worker → Repository archive: probes URL
- Download service worker → Browser downloads: starts download
- Detection and UI → Download service worker: requests repack
- Download service worker → Offscreen document: creates document
- Download service worker → Archive fetch and filtering: dispatches repack
- Archive fetch and filtering → Repository archive: fetches ZIP
- Archive fetch and filtering → ZIP reader and writer: reads and builds
- Archive fetch and filtering → Download service worker: returns blob URL
- Download service worker → Browser downloads: downloads repacked ZIP
- Download service worker → Detection and UI: reports progress