# apersongithub/duolingo-unlimited-hearts architecture

> Architecture diagram of the GitHub repository apersongithub/duolingo-unlimited-hearts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apersongithub/duolingo-unlimited-hearts
- Repository: https://github.com/apersongithub/duolingo-unlimited-hearts

## Overview

1. **What this repository is**
   - A browser add-on project that patches Duolingo at runtime, with two packaged extension targets:
     - `extension/stable/chrome`
     - `extension/stable/firefox`
   - It also ships standalone userscript variants in `userscript/` for browsers/environments that run userscripts instead of extensions.

2. **Primary product shape**
   - The core behavior is not a standalone app; it is a web-page interceptor and injector that modifies Duolingo’s client-side behavior as the user browses `duolingo.com` / `duolingo.cn`.
   - The README explicitly frames it as patching Duolingo assets and behavior, including “unpatched webpack chunk files” served from CloudFront.

3. **Main runtime boundaries**
   - **Background context**: `background.js` / `background.html` manages extension-wide behavior, settings, and likely request interception or update coordination.
   - **Content-script/page context**: `content_script.js`, `page_hook.js`, and `injection.js` bridge from extension context into the Duolingo page.
   - **UI surfaces**: `popup.*` and `options.*` provide user controls and configuration.
   - **Shared patch logic**: `shared/defaults.js` and `shared/patches.js` centralize defaults and patch definitions used by both browser builds.

4. **Injection and patching flow**
   - The patching path appears to be:
     1. User opens Duolingo.
     2. Extension loads content script.
     3. Content script hooks the page and injects patch code into page scope.
     4. Page hook/injection scripts alter page behavior and/or client bundle behavior.
   - This separation suggests the code needs both extension privileges and in-page execution rights, which is why there are dedicated hook and injection files.

5. **Network-level dependency**
   - A key architecture point is that the extension depends on Duolingo’s own delivery pipeline:
     - `duolingo.com` / `duolingo.cn` for the application page
     - `d35aaqx5ub95lt.cloudfront.net` for the JS chunk assets that get modified/overridden
   - The README also notes `raw.githubusercontent.com` is used to fetch `extension-version.json`, which acts as remote metadata for versioning, patch sync, update log, and banner content.

6. **Extension UI and user configuration**
   - The extension exposes a popup and options page in both browser builds:
     - `popup.html/css/js`
     - `options.html/css/js`
   - These are the control surfaces for enabling/disabling patch modes and related settings.
   - The only explicitly documented browser storage dependency is `storage`, used to persist patching mode and settings.

7. **Chrome vs Firefox packaging**
   - The Chrome and Firefox trees are parallel but not identical, indicating browser-specific packaging and manifest differences.
   - Both bundles include the same conceptual modules, but Firefox has `background.html` alongside `background.js`, which points to a browser-specific background-page/bootstrap pattern.
   - The duplicated structure suggests shared logic is manually mirrored rather than generated from one build pipeline in this repo.

8. **Userscript distribution**
   - `userscript/` contains separate `.user.js` builds:
     - `Duolingo Max.user.js`
     - `Duolingo Super.user.js`
     - `Duolingo Super Immersive.user.js`
     - `Duolingo Unlimited Hearts.user.js`
   - These are alternative delivery artifacts for environments like Safari + Userscripts on iPhone/iPad, bypassing the browser-extension packaging model.

9. **Patch set organization**
   - The `userscripts/patch4.js` through `patch7.js` files under each browser target suggest the patch logic is split into versioned or feature-specific chunks.
   - `shared/patches.js` likely selects and applies these patches, while `defaults.js` provides baseline configuration.
   - This implies the architecture is patch-driven rather than a monolithic script.

10. **Ancillary assets and docs**
   - `extension-version.json` at repo root is a remote-synced metadata file consumed by the extension.
   - `extras/` contains non-runtime materials: donation page, patcher notes, and release notes.
   - `.github/` is mostly release/support workflow and issue templates, not runtime architecture.

11. **External services and distribution**
   - The project is distributed through:
     - Mozilla Add-ons for Firefox
     - Chrome Web Store historically, but the README says that channel is no longer supported
     - GitHub Releases for manual installs
     - Greasyfork for userscripts
   - Those channels matter because they determine which artifact shape is used, but not the core patching architecture.

12. **Diagramming guidance**
   - The core diagram should show:
     - User browser loading Duolingo pages
     - Extension/userscript layer intercepting the page
     - Background/settings storage as a separate control plane
     - Injected page hooks modifying in-page behavior
     - Remote metadata fetch from GitHub
     - Duolingo and CloudFront as the external content sources being adapted

Main entry points: [`extension/stable/chrome/background.js`](https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/background.js) (Background), [`extension/stable/chrome/content_script.js`](https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/content_script.js) (Content script), [`extension/stable/chrome`](https://github.com/apersongithub/duolingo-unlimited-hearts/tree/main/extension/stable/chrome) (Chrome build), [`extension/stable/firefox`](https://github.com/apersongithub/duolingo-unlimited-hearts/tree/main/extension/stable/firefox) (Firefox build)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External systems"]
  node_browser(("Browser<br/>runtime"))
  node_duolingo_page(("Duolingo app<br/>site"))
  node_cloudfront_chunks(("Chunk assets<br/>asset CDN"))
  node_remote_meta["Version meta<br/>remote json"]
  node_storage[("Storage<br/>persistence")]
end

subgraph group_extension["Extension runtime"]
  node_chrome_bundle["Chrome build<br/>extension target"]
  node_firefox_bundle["Firefox build<br/>extension target"]
  node_chrome_bg["Background<br/>extension bg<br/>[background.js]"]
  node_content_script["Content script<br/>page bridge<br/>[content_script.js]"]
  node_page_hook["Page hook<br/>page bridge<br/>[page_hook.js]"]
  node_injection["Injection<br/>injector<br/>[injection.js]"]
  node_popup_ui["Popup UI<br/>extension ui<br/>[popup.html]"]
  node_options_ui["Options UI<br/>extension ui<br/>[options.html]"]
  node_shared_defaults["Defaults<br/>shared config<br/>[defaults.js]"]
  node_shared_patches["Patch logic<br/>shared patches<br/>[patches.js]"]
  node_patch_chunks["Patch chunks<br/>patch modules"]
end

subgraph group_userscript["Userscript delivery"]
  node_userscript_pack["Userscripts<br/>standalone delivery"]
end

node_browser -->|"loads"| node_chrome_bundle
node_browser -->|"loads"| node_firefox_bundle
node_chrome_bundle -->|"boots"| node_chrome_bg
node_firefox_bundle -->|"boots"| node_chrome_bg
node_chrome_bundle -->|"registers"| node_content_script
node_firefox_bundle -->|"registers"| node_content_script
node_content_script -->|"injects"| node_page_hook
node_page_hook -->|"passes through"| node_injection
node_injection -->|"patches"| node_duolingo_page
node_duolingo_page -->|"loads assets"| node_cloudfront_chunks
node_chrome_bg -->|"reads"| node_shared_defaults
node_chrome_bg -->|"applies"| node_shared_patches
node_chrome_bg -->|"persists"| node_storage
node_popup_ui -->|"controls"| node_chrome_bg
node_options_ui -->|"configures"| node_chrome_bg
node_shared_defaults -->|"feeds"| node_shared_patches
node_shared_patches -->|"selects"| node_patch_chunks
node_userscript_pack -.->|"bundles"| node_patch_chunks
node_remote_meta -->|"updates"| node_chrome_bg
node_browser -->|"runs"| node_userscript_pack
node_content_script -->|"messaging"| node_chrome_bg

click node_remote_meta "https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension-version.json"
click node_chrome_bundle "https://github.com/apersongithub/duolingo-unlimited-hearts/tree/main/extension/stable/chrome"
click node_firefox_bundle "https://github.com/apersongithub/duolingo-unlimited-hearts/tree/main/extension/stable/firefox"
click node_chrome_bg "https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/background.js"
click node_content_script "https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/content_script.js"
click node_page_hook "https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/page_hook.js"
click node_injection "https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/injection.js"
click node_popup_ui "https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/popup.html"
click node_options_ui "https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/options.html"
click node_shared_defaults "https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/shared/defaults.js"
click node_shared_patches "https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/shared/patches.js"
click node_patch_chunks "https://github.com/apersongithub/duolingo-unlimited-hearts/tree/main/extension/stable/chrome/userscripts"
click node_userscript_pack "https://github.com/apersongithub/duolingo-unlimited-hearts/tree/main/userscript"

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_browser,node_duolingo_page,node_cloudfront_chunks,node_remote_meta,node_storage toneBlue
class node_chrome_bundle,node_firefox_bundle,node_chrome_bg,node_content_script,node_page_hook,node_injection,node_popup_ui,node_options_ui,node_shared_defaults,node_shared_patches,node_patch_chunks toneAmber
class node_userscript_pack toneMint
```

## Components

### External systems

Duolingo runtime, delivery assets, remote metadata, and browser storage

- **Browser**: runtime · Host browser running the add-on or userscript
- **Duolingo app**: site · Duolingo pages the repo patches at runtime
- **Chunk assets**: asset CDN · Duolingo webpack chunk delivery served from CloudFront
- [Version meta](https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension-version.json): remote json · extension-version.json fetched from GitHub raw content · `extension-version.json`
- **Storage**: persistence · Browser storage used for settings and patch mode

### Extension runtime

Packaged browser extension targets and their in-page injection flow

- [Chrome build](https://github.com/apersongithub/duolingo-unlimited-hearts/tree/main/extension/stable/chrome): extension target · Packaged Chrome extension tree · `extension/stable/chrome`
- [Firefox build](https://github.com/apersongithub/duolingo-unlimited-hearts/tree/main/extension/stable/firefox): extension target · Packaged Firefox extension tree · `extension/stable/firefox`
- [Background](https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/background.js): extension bg · Extension control plane and coordination entrypoint · `extension/stable/chrome/background.js`
- [Content script](https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/content_script.js): page bridge · Injected bridge between extension context and Duolingo page · `extension/stable/chrome/content_script.js`
- [Page hook](https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/page_hook.js): page bridge · Page-context hook used to reach in-page Duolingo code · `extension/stable/chrome/page_hook.js`
- [Injection](https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/injection.js): injector · Script that enters page scope and applies runtime changes · `extension/stable/chrome/injection.js`
- [Popup UI](https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/popup.html): extension ui · Quick controls for patch state and actions · `extension/stable/chrome/popup.html`
- [Options UI](https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/options.html): extension ui · Settings surface for persistent configuration · `extension/stable/chrome/options.html`
- [Defaults](https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/shared/defaults.js): shared config · Baseline settings shared by browser builds · `extension/stable/chrome/shared/defaults.js`
- [Patch logic](https://github.com/apersongithub/duolingo-unlimited-hearts/blob/main/extension/stable/chrome/shared/patches.js): shared patches · Central patch definitions and selection logic · `extension/stable/chrome/shared/patches.js`
- [Patch chunks](https://github.com/apersongithub/duolingo-unlimited-hearts/tree/main/extension/stable/chrome/userscripts): patch modules · Versioned/feature patch fragments used by the injected runtime · `extension/stable/chrome/userscripts`

### Userscript delivery

Standalone .user.js artifacts for userscript-capable browsers

- [Userscripts](https://github.com/apersongithub/duolingo-unlimited-hearts/tree/main/userscript): standalone delivery · Standalone .user.js builds for userscript environments · `userscript`

## Connections

- Browser → Chrome build: loads · Browser loads the Chrome extension package
- Browser → Firefox build: loads · Browser loads the Firefox extension package
- Chrome build → Background: boots · Chrome package starts its background logic
- Firefox build → Background: boots · Firefox package mirrors the same background role
- Chrome build → Content script: registers · Extension installs the page bridge content script
- Firefox build → Content script: registers · Firefox build installs the page bridge content script
- Content script → Page hook: injects · Content script enters page context through a hook
- Page hook → Injection: passes through · Hook hands execution to the injected patch runtime
- Injection → Duolingo app: patches · Injected code changes Duolingo page behavior at runtime
- Duolingo app → Chunk assets: loads assets · Duolingo app consumes chunk files from CloudFront
- Background → Defaults: reads · Background logic uses shared baseline settings
- Background → Patch logic: applies · Background coordinates patch definitions
- Background → Storage: persists · Settings and patch mode are stored in browser storage
- Popup UI → Background: controls · Popup provides quick actions for the background plane
- Options UI → Background: configures · Options page writes persistent settings via background
- Defaults → Patch logic: feeds · Defaults seed patch selection and behavior
- Patch logic → Patch chunks: selects · Patch registry resolves the patch chunk set
- Userscripts → Patch chunks: bundles · Standalone userscripts package the same patch-oriented logic
- Version meta → Background: updates · Remote metadata informs versioning and patch sync
- Browser → Userscripts: runs · Userscript-capable browsers execute the standalone artifacts
- Content script → Background: messaging · Content script exchanges state and commands with background
