# platformer444/scratchaddons architecture

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

- Interactive diagram: https://gitdiagram.com/platformer444/scratchaddons
- Repository: https://github.com/platformer444/scratchaddons

## Overview

Scratch Addons is a browser extension that lets users enable and configure community-built features and themes for Scratch. The main workflow runs from settings and manifest-based addon selection through background coordination and content-script injection, where userscripts use the addon API to interact with Scratch pages. The extension also provides popup surfaces, authentication/session handling, and Scratch Messaging. The README documents manifest-driven injection and broader addon capabilities; unsampled implementation details are represented only where the file tree or README supports them.

Main entry points: [`background`](https://github.com/platformer444/scratchaddons/tree/master/background) (Background coordinator), [`webpages/popup/index.js`](https://github.com/platformer444/scratchaddons/blob/master/webpages/popup/index.js) (Extension popup), [`addons`](https://github.com/platformer444/scratchaddons/tree/master/addons) (Addon catalog), [`webpages/settings/index.js`](https://github.com/platformer444/scratchaddons/blob/master/webpages/settings/index.js) (Settings interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_configuration["Configuration"]
  node_settings["Settings interface<br/>[index.js]"]
  node_manifests["Addon manifests"]
  node_error_page["Error page<br/>[index.js]"]
end

subgraph group_runtime["Extension runtime"]
  node_background["Background coordinator"]
  node_userscript_loader["Userscript injection<br/>[run-userscript.js]"]
  node_content_scripts["Content scripts<br/>[cs.js]"]
  node_addon_api["Addon APIs<br/>[Addon.js]"]
  node_redux["Redux bridge<br/>[ReduxHandler.js]"]
end

subgraph group_page["Scratch page features"]
  node_addon_catalog["Addon catalog"]
  node_editor_features["Editor features<br/>[userscript.js]"]
  node_site_features["Website features"]
end

subgraph group_services["Services and state"]
  node_settings_store[("Settings storage")]
  node_auth["Session and auth<br/>[handle-auth.js]"]
end

subgraph group_surfaces["Popup surfaces"]
  node_popup["Extension popup<br/>[index.js]"]
  node_messaging_popup["Scratch Messaging<br/>[popup.js]"]
  node_cloud_games_popup["Cloud Games popup<br/>[popup.js]"]
end

node_user(("Extension user"))
node_scratch_site(("Scratch website"))
node_scratch_services(("Scratch services"))

node_user -->|"configures addons"| node_settings
node_settings -->|"reads and writes"| node_settings_store
node_settings -->|"sends settings changes"| node_background
node_background -->|"loads manifests"| node_manifests
node_background -->|"reads settings"| node_settings_store
node_background -->|"provides addon runtime data"| node_userscript_loader
node_userscript_loader -->|"injects scripts"| node_content_scripts
node_content_scripts -->|"runs enabled addons"| node_addon_catalog
node_addon_catalog -->|"uses APIs"| node_addon_api
node_addon_api -->|"interacts with page"| node_scratch_site
node_addon_api -->|"reads and dispatches state"| node_redux
node_redux -->|"observes page state"| node_scratch_site
node_addon_catalog -->|"includes editor features"| node_editor_features
node_addon_catalog -->|"includes site themes"| node_site_features
node_user -->|"opens popup"| node_popup
node_popup -->|"requests addon settings"| node_background
node_popup -->|"opens quick settings"| node_settings
node_popup -->|"opens enabled popup"| node_messaging_popup
node_popup -->|"opens enabled popup"| node_cloud_games_popup
node_background -->|"tracks session"| node_auth
node_auth -->|"fetches session and cookies"| node_scratch_services
node_auth -->|"notifies session changes"| node_content_scripts
node_user -->|"uses Scratch"| node_scratch_site

click node_settings "https://github.com/platformer444/scratchaddons/blob/master/webpages/settings/index.js"
click node_manifests "https://github.com/platformer444/scratchaddons/blob/master/background/load-addon-manifests.js"
click node_background "https://github.com/platformer444/scratchaddons/tree/master/background"
click node_userscript_loader "https://github.com/platformer444/scratchaddons/blob/master/content-scripts/inject/run-userscript.js"
click node_content_scripts "https://github.com/platformer444/scratchaddons/blob/master/content-scripts/cs.js"
click node_addon_api "https://github.com/platformer444/scratchaddons/blob/master/addon-api/content-script/Addon.js"
click node_addon_catalog "https://github.com/platformer444/scratchaddons/tree/master/addons"
click node_editor_features "https://github.com/platformer444/scratchaddons/blob/master/addons/paint-snap/userscript.js"
click node_site_features "https://github.com/platformer444/scratchaddons/blob/master/addons/dark-www/experimental_forums_preview.js"
click node_redux "https://github.com/platformer444/scratchaddons/blob/master/addon-api/content-script/ReduxHandler.js"
click node_auth "https://github.com/platformer444/scratchaddons/blob/master/background/handle-auth.js"
click node_popup "https://github.com/platformer444/scratchaddons/blob/master/webpages/popup/index.js"
click node_messaging_popup "https://github.com/platformer444/scratchaddons/blob/master/popups/scratch-messaging/popup.js"
click node_cloud_games_popup "https://github.com/platformer444/scratchaddons/blob/master/popups/cloud-games/popup.js"
click node_error_page "https://github.com/platformer444/scratchaddons/blob/master/webpages/error/index.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_settings,node_manifests,node_error_page,node_user toneBlue
class node_background,node_userscript_loader,node_content_scripts,node_addon_api,node_redux toneAmber
class node_addon_catalog,node_editor_features,node_site_features toneMint
class node_settings_store,node_auth toneRose
class node_popup,node_messaging_popup,node_cloud_games_popup,node_scratch_site,node_scratch_services toneIndigo
```

## Components

### Configuration

- [Settings interface](https://github.com/platformer444/scratchaddons/blob/master/webpages/settings/index.js): `webpages/settings/index.js`
- [Addon manifests](https://github.com/platformer444/scratchaddons/blob/master/background/load-addon-manifests.js): `background/load-addon-manifests.js`
- [Error page](https://github.com/platformer444/scratchaddons/blob/master/webpages/error/index.js): `webpages/error/index.js`

### Extension runtime

- [Background coordinator](https://github.com/platformer444/scratchaddons/tree/master/background): `background`
- [Userscript injection](https://github.com/platformer444/scratchaddons/blob/master/content-scripts/inject/run-userscript.js): `content-scripts/inject/run-userscript.js`
- [Content scripts](https://github.com/platformer444/scratchaddons/blob/master/content-scripts/cs.js): `content-scripts/cs.js`
- [Addon APIs](https://github.com/platformer444/scratchaddons/blob/master/addon-api/content-script/Addon.js): `addon-api/content-script/Addon.js`
- [Redux bridge](https://github.com/platformer444/scratchaddons/blob/master/addon-api/content-script/ReduxHandler.js): `addon-api/content-script/ReduxHandler.js`

### Scratch page features

- [Addon catalog](https://github.com/platformer444/scratchaddons/tree/master/addons): `addons`
- [Editor features](https://github.com/platformer444/scratchaddons/blob/master/addons/paint-snap/userscript.js): `addons/paint-snap/userscript.js`
- [Website features](https://github.com/platformer444/scratchaddons/blob/master/addons/dark-www/experimental_forums_preview.js): `addons/dark-www/experimental_forums_preview.js`

### Services and state

- **Settings storage**
- [Session and auth](https://github.com/platformer444/scratchaddons/blob/master/background/handle-auth.js): `background/handle-auth.js`

### Popup surfaces

- [Extension popup](https://github.com/platformer444/scratchaddons/blob/master/webpages/popup/index.js): `webpages/popup/index.js`
- [Scratch Messaging](https://github.com/platformer444/scratchaddons/blob/master/popups/scratch-messaging/popup.js): `popups/scratch-messaging/popup.js`
- [Cloud Games popup](https://github.com/platformer444/scratchaddons/blob/master/popups/cloud-games/popup.js): `popups/cloud-games/popup.js`

### Other components

- **Extension user**
- **Scratch website**
- **Scratch services**

## Connections

- Extension user → Settings interface: configures addons
- Settings interface → Settings storage: reads and writes
- Settings interface → Background coordinator: sends settings changes
- Background coordinator → Addon manifests: loads manifests
- Background coordinator → Settings storage: reads settings
- Background coordinator → Userscript injection: provides addon runtime data
- Userscript injection → Content scripts: injects scripts
- Content scripts → Addon catalog: runs enabled addons
- Addon catalog → Addon APIs: uses APIs
- Addon APIs → Scratch website: interacts with page
- Addon APIs → Redux bridge: reads and dispatches state
- Redux bridge → Scratch website: observes page state
- Addon catalog → Editor features: includes editor features
- Addon catalog → Website features: includes site themes
- Extension user → Extension popup: opens popup
- Extension popup → Background coordinator: requests addon settings
- Extension popup → Settings interface: opens quick settings
- Extension popup → Scratch Messaging: opens enabled popup
- Extension popup → Cloud Games popup: opens enabled popup
- Background coordinator → Session and auth: tracks session
- Session and auth → Scratch services: fetches session and cookies
- Session and auth → Content scripts: notifies session changes
- Extension user → Scratch website: uses Scratch