# scratchfoundation/scratch-gui architecture

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

- Interactive diagram: https://gitdiagram.com/scratchfoundation/scratch-gui
- Repository: https://github.com/scratchfoundation/scratch-gui

## Overview

Scratch GUI is a React interface for creating and running Scratch 3.0 projects. The user-facing workflow enters the editor, presents project controls and visual programming tools, and runs the project through the Scratch VM. The map also preserves asset editing and libraries, tutorials, cloud support, and state management. The README and excerpts establish the main UI and several integrations; unsampled subsystems are represented only where the tree and source index support them, so some connections are intentionally omitted.

Main entry points: [`src/containers/gui.jsx`](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/containers/gui.jsx) (GUI container), [`src/index.js`](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/index.js) (GUI entry), [`src/components/gui/gui.jsx`](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/components/gui/gui.jsx) (Editor layout), [`src/containers/blocks.jsx`](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/containers/blocks.jsx) (Block workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application shell"]
  node_entry["GUI entry<br/>[index.js]"]
  node_appstate["App state<br/>[app-state-hoc.jsx]"]
  node_gui["Editor layout<br/>[gui.jsx]"]
  node_gui_container["GUI container<br/>[gui.jsx]"]
  node_menubar["Menu bar<br/>[menu-bar.jsx]"]
end

subgraph group_editor["Project editor"]
  node_blocks["Block workspace<br/>[blocks.jsx]"]
  node_toolbox["Toolbox generation"]
  node_block_engine["Block integration<br/>[blocks.js]"]
  node_target["Target pane<br/>[target-pane.jsx]"]
  node_stage["Stage view<br/>[stage.jsx]"]
  node_asset_editor["Costume editor<br/>[costume-tab.jsx]"]
  node_sound_editor["Sound editor<br/>[sound-editor.jsx]"]
  node_sound_ui["Sound editor UI<br/>[sound-editor.jsx]"]
end

subgraph group_runtime["Project runtime"]
  node_vm_manager["VM lifecycle<br/>[vm-manager-hoc.jsx]"]
  node_vm["Scratch VM"]
  node_audio["Audio engine"]
  node_cloud_manager["Cloud connection manager"]
  node_cloud_provider["Cloud provider<br/>[cloud-provider.js]"]
end

subgraph group_content["Content and assets"]
  node_libraries["Asset libraries<br/>[library.jsx]"]
  node_tutorials["Tutorial decks<br/>[index.jsx]"]
  node_backpack["Backpack<br/>[backpack.jsx]"]
  node_storage["Project and asset storage<br/>[storage.js]"]
end

subgraph group_state["State management"]
  node_gui_state["GUI state<br/>[gui.js]"]
  node_project_state["Project state<br/>[project-state.js]"]
  node_alerts_state["Alert state<br/>[alerts.js]"]
  node_cards_state["Tutorial state<br/>[cards.js]"]
  node_editor_tab["Editor tab state<br/>[editor-tab.js]"]
  node_locales["Locale state<br/>[locales.js]"]
  node_modals["Modal state<br/>[modals.js]"]
end

node_user(("Project creator"))

node_user -->|"opens editor"| node_entry
node_entry -->|"exports"| node_gui_container
node_entry -->|"exports"| node_appstate
node_entry -->|"registers reducer"| node_gui_state
node_entry -->|"registers reducer"| node_locales
node_gui_container -->|"renders"| node_gui
node_gui -->|"renders"| node_blocks
node_gui -->|"renders"| node_target
node_gui -->|"renders stage wrapper"| node_stage
node_blocks -->|"initializes"| node_block_engine
node_blocks -->|"generates toolbox"| node_toolbox
node_gui_container -->|"composes lifecycle"| node_vm_manager
node_vm_manager -->|"initializes and loads"| node_vm
node_vm_manager -->|"attaches engine"| node_audio
node_cloud_manager -->|"creates provider"| node_cloud_provider
node_cloud_manager -->|"sets cloud provider"| node_vm
node_gui_container -->|"reads project state"| node_project_state
node_gui_container -->|"configures storage"| node_storage
node_asset_editor -->|"uses asset panel"| node_libraries
node_sound_editor -->|"renders editor"| node_sound_ui
node_libraries -->|"loads deck data"| node_tutorials
node_gui -->|"renders"| node_menubar
node_gui_container -->|"connects state"| node_gui_state
node_blocks -->|"dispatches tab change"| node_editor_tab
node_cloud_manager -->|"shows cloud alert"| node_alerts_state
node_gui_container -->|"connects modal state"| node_modals
node_gui_container -->|"connects tutorial state"| node_cards_state
node_backpack -.->|"uses asset storage"| node_storage
node_storage -.->|"reads and writes remotely"| node_user

click node_entry "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/index.js"
click node_appstate "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/lib/app-state-hoc.jsx"
click node_gui "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/components/gui/gui.jsx"
click node_gui_container "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/containers/gui.jsx"
click node_menubar "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/components/menu-bar/menu-bar.jsx"
click node_blocks "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/containers/blocks.jsx"
click node_toolbox "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/lib/make-toolbox-xml.js"
click node_block_engine "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/lib/blocks.js"
click node_target "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/containers/target-pane.jsx"
click node_stage "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/containers/stage.jsx"
click node_asset_editor "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/containers/costume-tab.jsx"
click node_sound_editor "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/containers/sound-editor.jsx"
click node_sound_ui "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/components/sound-editor/sound-editor.jsx"
click node_libraries "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/components/library/library.jsx"
click node_tutorials "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/lib/libraries/decks/index.jsx"
click node_backpack "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/containers/backpack.jsx"
click node_storage "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/lib/storage.js"
click node_vm_manager "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/lib/vm-manager-hoc.jsx"
click node_cloud_manager "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/lib/cloud-manager-hoc.jsx"
click node_cloud_provider "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/lib/cloud-provider.js"
click node_gui_state "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/reducers/gui.js"
click node_project_state "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/reducers/project-state.js"
click node_alerts_state "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/reducers/alerts.js"
click node_cards_state "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/reducers/cards.js"
click node_editor_tab "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/reducers/editor-tab.js"
click node_locales "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/reducers/locales.js"
click node_modals "https://github.com/scratchfoundation/scratch-gui/blob/develop/src/reducers/modals.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_entry,node_appstate,node_gui,node_gui_container,node_menubar toneBlue
class node_blocks,node_toolbox,node_block_engine,node_target,node_stage,node_asset_editor,node_sound_editor,node_sound_ui toneAmber
class node_vm_manager,node_vm,node_audio,node_cloud_manager,node_cloud_provider toneMint
class node_libraries,node_tutorials,node_backpack,node_storage toneRose
class node_gui_state,node_project_state,node_alerts_state,node_cards_state,node_editor_tab,node_locales,node_modals,node_user toneIndigo
```

## Components

### Application shell

- [GUI entry](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/index.js): `src/index.js`
- [App state](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/lib/app-state-hoc.jsx): `src/lib/app-state-hoc.jsx`
- [Editor layout](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/components/gui/gui.jsx): `src/components/gui/gui.jsx`
- [GUI container](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/containers/gui.jsx): `src/containers/gui.jsx`
- [Menu bar](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/components/menu-bar/menu-bar.jsx): `src/components/menu-bar/menu-bar.jsx`

### Project editor

- [Block workspace](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/containers/blocks.jsx): `src/containers/blocks.jsx`
- [Toolbox generation](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/lib/make-toolbox-xml.js): `src/lib/make-toolbox-xml.js`
- [Block integration](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/lib/blocks.js): `src/lib/blocks.js`
- [Target pane](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/containers/target-pane.jsx): `src/containers/target-pane.jsx`
- [Stage view](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/containers/stage.jsx): `src/containers/stage.jsx`
- [Costume editor](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/containers/costume-tab.jsx): `src/containers/costume-tab.jsx`
- [Sound editor](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/containers/sound-editor.jsx): `src/containers/sound-editor.jsx`
- [Sound editor UI](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/components/sound-editor/sound-editor.jsx): `src/components/sound-editor/sound-editor.jsx`

### Project runtime

- [VM lifecycle](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/lib/vm-manager-hoc.jsx): `src/lib/vm-manager-hoc.jsx`
- **Scratch VM**
- **Audio engine**
- [Cloud connection manager](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/lib/cloud-manager-hoc.jsx): `src/lib/cloud-manager-hoc.jsx`
- [Cloud provider](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/lib/cloud-provider.js): `src/lib/cloud-provider.js`

### Content and assets

- [Asset libraries](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/components/library/library.jsx): `src/components/library/library.jsx`
- [Tutorial decks](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/lib/libraries/decks/index.jsx): `src/lib/libraries/decks/index.jsx`
- [Backpack](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/containers/backpack.jsx): `src/containers/backpack.jsx`
- [Project and asset storage](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/lib/storage.js): `src/lib/storage.js`

### State management

- [GUI state](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/reducers/gui.js): `src/reducers/gui.js`
- [Project state](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/reducers/project-state.js): `src/reducers/project-state.js`
- [Alert state](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/reducers/alerts.js): `src/reducers/alerts.js`
- [Tutorial state](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/reducers/cards.js): `src/reducers/cards.js`
- [Editor tab state](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/reducers/editor-tab.js): `src/reducers/editor-tab.js`
- [Locale state](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/reducers/locales.js): `src/reducers/locales.js`
- [Modal state](https://github.com/scratchfoundation/scratch-gui/blob/develop/src/reducers/modals.js): `src/reducers/modals.js`

### Other components

- **Project creator**

## Connections

- Project creator → GUI entry: opens editor
- GUI entry → GUI container: exports (evidence: `src/index.js`)
- GUI entry → App state: exports (evidence: `src/index.js`)
- GUI entry → GUI state: registers reducer (evidence: `src/index.js`)
- GUI entry → Locale state: registers reducer (evidence: `src/index.js`)
- GUI container → Editor layout: renders (evidence: `src/containers/gui.jsx`)
- Editor layout → Block workspace: renders (evidence: `src/components/gui/gui.jsx`)
- Editor layout → Target pane: renders (evidence: `src/components/gui/gui.jsx`)
- Editor layout → Stage view: renders stage wrapper (evidence: `src/components/gui/gui.jsx`)
- Block workspace → Block integration: initializes (evidence: `src/containers/blocks.jsx`)
- Block workspace → Toolbox generation: generates toolbox (evidence: `src/containers/blocks.jsx`)
- GUI container → VM lifecycle: composes lifecycle (evidence: `src/containers/gui.jsx`)
- VM lifecycle → Scratch VM: initializes and loads (evidence: `src/lib/vm-manager-hoc.jsx`)
- VM lifecycle → Audio engine: attaches engine (evidence: `src/lib/vm-manager-hoc.jsx`)
- Cloud connection manager → Cloud provider: creates provider (evidence: `src/lib/cloud-manager-hoc.jsx`)
- Cloud connection manager → Scratch VM: sets cloud provider (evidence: `src/lib/cloud-manager-hoc.jsx`)
- GUI container → Project state: reads project state (evidence: `src/containers/gui.jsx`)
- GUI container → Project and asset storage: configures storage (evidence: `src/containers/gui.jsx`)
- Costume editor → Asset libraries: uses asset panel (evidence: `src/containers/costume-tab.jsx`)
- Sound editor → Sound editor UI: renders editor (evidence: `src/containers/sound-editor.jsx`)
- Asset libraries → Tutorial decks: loads deck data (evidence: `src/components/library/library.jsx`)
- Editor layout → Menu bar: renders (evidence: `src/components/gui/gui.jsx`)
- GUI container → GUI state: connects state (evidence: `src/containers/gui.jsx`)
- Block workspace → Editor tab state: dispatches tab change (evidence: `src/containers/blocks.jsx`)
- Cloud connection manager → Alert state: shows cloud alert (evidence: `src/lib/cloud-manager-hoc.jsx`)
- GUI container → Modal state: connects modal state (evidence: `src/containers/gui.jsx`)
- GUI container → Tutorial state: connects tutorial state (evidence: `src/containers/gui.jsx`)
- Backpack → Project and asset storage: uses asset storage
- Project and asset storage → Project creator: reads and writes remotely
