# sugarlabs/musicblocks architecture

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

- Interactive diagram: https://gitdiagram.com/sugarlabs/musicblocks
- Repository: https://github.com/sugarlabs/musicblocks

## Overview

1. **Overall shape**
   - Music Blocks is a browser-based visual programming environment for music and graphics.
   - The core app is a single-page frontend centered on `index.html` / `index.js`, with most behavior implemented in vanilla JavaScript under `js/`.
   - It also ships as a PWA/mobile package and has an Electron entry point (`electron-main.js`) plus Android packaging metadata (`config.xml`, `manifest.*`).

2. **Primary runtime boundary**
   - The main execution boundary is the browser: UI rendering, event handling, audio synthesis, and persistence all happen client-side.
   - A local web server is recommended for asset loading and full functionality; the repo includes dev tooling for serving, testing, linting, and packaging.

3. **Core interaction model**
   - Users compose music/graphics programs by dragging blocks in the workspace.
   - Blocks are organized into palettes and translated into executable behavior by the runtime.
   - Execution drives “turtles” that produce sound, visuals, and stateful actions.

4. **Block system**
   - `js/blocks/` contains the domain-specific block families, grouped by concept: pitch, rhythm, drums, tone, graphics, pen, intervals, meter, sensors, flow, numbers, booleans, dictionaries, widgets, etc.
   - Shared block infrastructure lives in `js/block.js`, `js/blocks.js`, `js/blockfactory.js`, and `js/protoblocks.js`.
   - These modules define block creation, palette registration, dependencies, and serialization-friendly representations.

5. **Execution and music engine**
   - `js/logo.js`, `js/LogoDependencies.js`, and related files implement the interpreter/execution layer that walks block structures and schedules actions.
   - The turtle runtime (`js/turtle.js`, `js/turtles.js`, `js/turtleactions/`, `js/turtle-singer.js`, `js/turtle-painter.js`) is the bridge from blocks to output.
   - This layer coordinates musical notes, timing, articulation, and drawing on a per-turtle basis.

6. **Audio, notation, and export**
   - Audio and musical output are handled through utility modules such as `js/midi.js`, `js/mxml.js`, `js/lilypond.js`, `js/notation.js`, and sound adapters in `js/p5-sound-adapter.js`.
   - `sounds/` contains sampled instruments, and `lib/midi.js` and `lib/voices/` support playback/speech features.
   - There is a separate JS-to-block export path in `js/js-export/`, which converts JavaScript representations back into block structures via AST and conversion utilities.

7. **UI shell and controls**
   - The top-level application UI is assembled from modules like `js/toolbar.js`, `js/palette.js`, `js/pastebox.js`, `js/trash.js`, `js/themebox.js`, `js/languagebox.js`, and `js/piemenus.js`.
   - The workspace is highly interactive and uses mouse/keyboard events plus custom dialogs and overlays from `js/utils/` and `js/widgets/`.
   - Styling is split across `css/`, `dist/css/`, `fonts/`, `images/`, and `lib/` assets.

8. **Widgets subsystem**
   - `js/widgets/` holds secondary interactive tools such as the keyboard, tempo, tuner, oscillator scope, rhythm ruler, sampler, mode/temperament tools, AI debug widget, and reflection/help components.
   - Widgets are not the main programming surface; they are auxiliary panels that inspect, edit, or generate musical material.
   - Several widgets have their own sub-APIs and tests, indicating they are modular UI subsystems rather than simple dialogs.

9. **Planet sharing and project storage**
   - The `planet/` directory is a distinct subsystem for project browsing, publishing, viewing, caching, and server/local synchronization.
   - It includes local storage and remote request abstractions (`ProjectStorage`, `RequestManager`, `ServerInterface`, `CacheManager`, `Publisher`, `SaveInterface`) and a separate UI shell (`planet/index.html`, `planet/js/main.js`).
   - This subsystem is the architecture’s boundary to project sharing and remix workflows; it is not required for core offline use.

10. **Localization and content pipeline**
   - Translations are managed through `locales/` JSON files and `po/` source translations.
   - `convert_po_to_json.py` and `po-to-json-validation` automation indicate a build-time translation conversion pipeline.
   - User-facing documentation is also heavily localized, with language-specific docs under `Docs/` and translated guides/manuals.

11. **Build, packaging, and deployment**
   - Tooling includes Node-based workflows (`package.json`, `gulpfile.*`, `jest.config.js`, `eslint.config.mjs`, `cypress.config.js`, `lighthouserc.js`) plus Docker support.
   - The repo produces browser assets, distribution CSS, and packaged app targets; CI covers linting, unit tests, Cypress E2E, Lighthouse, and security scanning.
   - Service worker and manifest files (`sw.js`, `lib/sw.js`, `manifest.json`, `manifest.webapp`) support offline/PWA behavior.

12. **Test and quality boundaries**
   - Tests are extensive and mirror the main architecture: block logic, turtle execution, utilities, widgets, export pipeline, and Planet components all have unit coverage under `js/**/__tests__` and `planet/js/__tests__`.
   - End-to-end browser behavior is validated in `cypress/e2e/`.
   - This test layout reflects the repo’s main boundaries: block model, execution engine, UI widgets, and sharing/storage subsystem.

13. **External dependencies that matter architecturally**
   - The app relies on browser-native APIs, plus a few bundled libraries in `lib/` such as jQuery, require.js, Chart.js, and code editor/highlight assets.
   - Audio and speech capabilities depend on bundled samples/voice data and browser audio behavior.
   - The important architectural point is that most dependencies are vendored and front-end focused; there is no central backend service required for basic operation.

14. **How to diagram it**
   - A useful diagram should show: browser UI and asset layer at the top; block palette/workspace in the middle; the logo interpreter and turtle/audio engine beneath; widgets as sidecar tools connected to the same runtime; and the Planet/project-sharing subsystem as an optional external-facing branch.
   - Separate the offline core from optional services like sharing, localization conversion, and packaging/testing infrastructure.

Main entry points: [`js/activity.js`](https://github.com/sugarlabs/musicblocks/blob/master/js/activity.js) (Activity core), [`package.json`](https://github.com/sugarlabs/musicblocks/blob/master/package.json) (Build tools), [`js/widgets/widgetWindows.js`](https://github.com/sugarlabs/musicblocks/blob/master/js/widgets/widgetWindows.js) (Widgets), [`js/logo.js`](https://github.com/sugarlabs/musicblocks/blob/master/js/logo.js) (Logo runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core app"]
  node_index["App shell<br/>browser entry<br/>[index.html]"]
  node_indexjs["Startup code<br/>bootstrap<br/>[index.js]"]
  node_activity["Activity core<br/>app state<br/>[activity.js]"]
  node_workspace["Workspace<br/>block editor<br/>[blocks.js]"]
  node_blockinfra["Block model<br/>block infra<br/>[block.js]"]
  node_blockfamilies["Block families<br/>domain blocks<br/>[PitchBlocks.js]"]
end

subgraph group_ui["UI shell"]
  node_toolbar["Toolbar<br/>ui chrome<br/>[toolbar.js]"]
  node_palettes["Palettes<br/>ui panels<br/>[palette.js]"]
  node_widgets["Widgets<br/>aux panels<br/>[widgetWindows.js]"]
end

subgraph group_runtime["Runtime and output"]
  node_interpreter["Logo runtime<br/>interpreter<br/>[logo.js]"]
  node_turtles["Turtle engine<br/>execution runtime<br/>[turtles.js]"]
  node_turtleactions["Turtle actions<br/>action layer<br/>[PitchActions.js]"]
  node_audio["Audio stack<br/>music output<br/>[midi.js]"]
  node_exportjs["JS export<br/>conversion pipeline<br/>[export.js]"]
end

subgraph group_sharing["Planet sharing"]
  node_planet["Planet<br/>sharing subsystem<br/>[Planet.js]"]
  node_planetstorage["Project storage<br/>sharing storage<br/>[ProjectStorage.js]"]
end

subgraph group_support["Build and support"]
  node_locale["Locales<br/>i18n assets<br/>[en.json]"]
  node_build["Build tools<br/>tooling<br/>[package.json]"]
  node_docs["Docs<br/>documentation<br/>[index.html]"]
  node_libs["Vendored libs<br/>third-party assets<br/>[require.js]"]
end

node_index -->|"boots"| node_indexjs
node_indexjs -->|"initializes"| node_activity
node_activity -->|"assembles"| node_toolbar
node_activity -->|"mounts"| node_palettes
node_activity -->|"opens"| node_widgets
node_activity -.->|"links"| node_planet
node_workspace -->|"uses"| node_blockinfra
node_blockinfra -->|"organizes"| node_blockfamilies
node_blockfamilies -->|"compile to"| node_interpreter
node_interpreter -->|"drives"| node_turtles
node_turtles -->|"dispatches"| node_turtleactions
node_turtleactions -->|"produces"| node_audio
node_audio -.->|"adapts with"| node_libs
node_interpreter -.->|"supports"| node_exportjs
node_widgets -->|"inspects"| node_turtles
node_widgets -->|"controls"| node_audio
node_planet -->|"persists"| node_planetstorage
node_planet -.->|"integrates"| node_activity
node_build -->|"packages"| node_index
node_build -.->|"validates"| node_docs
node_build -.->|"generates"| node_locale
node_docs -.->|"describes"| node_workspace
node_libs -.->|"supports"| node_index

click node_index "https://github.com/sugarlabs/musicblocks/blob/master/index.html"
click node_indexjs "https://github.com/sugarlabs/musicblocks/blob/master/index.js"
click node_activity "https://github.com/sugarlabs/musicblocks/blob/master/js/activity.js"
click node_workspace "https://github.com/sugarlabs/musicblocks/blob/master/js/blocks.js"
click node_blockinfra "https://github.com/sugarlabs/musicblocks/blob/master/js/block.js"
click node_blockfamilies "https://github.com/sugarlabs/musicblocks/blob/master/js/blocks/PitchBlocks.js"
click node_interpreter "https://github.com/sugarlabs/musicblocks/blob/master/js/logo.js"
click node_turtles "https://github.com/sugarlabs/musicblocks/blob/master/js/turtles.js"
click node_turtleactions "https://github.com/sugarlabs/musicblocks/blob/master/js/turtleactions/PitchActions.js"
click node_audio "https://github.com/sugarlabs/musicblocks/blob/master/js/midi.js"
click node_exportjs "https://github.com/sugarlabs/musicblocks/blob/master/js/js-export/export.js"
click node_toolbar "https://github.com/sugarlabs/musicblocks/blob/master/js/toolbar.js"
click node_palettes "https://github.com/sugarlabs/musicblocks/blob/master/js/palette.js"
click node_widgets "https://github.com/sugarlabs/musicblocks/blob/master/js/widgets/widgetWindows.js"
click node_planet "https://github.com/sugarlabs/musicblocks/blob/master/planet/js/Planet.js"
click node_planetstorage "https://github.com/sugarlabs/musicblocks/blob/master/planet/js/ProjectStorage.js"
click node_locale "https://github.com/sugarlabs/musicblocks/blob/master/locales/en.json"
click node_build "https://github.com/sugarlabs/musicblocks/blob/master/package.json"
click node_docs "https://github.com/sugarlabs/musicblocks/blob/master/Docs/guide/index.html"
click node_libs "https://github.com/sugarlabs/musicblocks/blob/master/lib/require.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_index,node_indexjs,node_activity,node_workspace,node_blockinfra,node_blockfamilies toneBlue
class node_toolbar,node_palettes,node_widgets toneAmber
class node_interpreter,node_turtles,node_turtleactions,node_audio,node_exportjs toneMint
class node_planet,node_planetstorage toneRose
class node_locale,node_build,node_docs,node_libs toneIndigo
```

## Components

### Core app

Browser-based visual programming environment and its execution engine.

- [App shell](https://github.com/sugarlabs/musicblocks/blob/master/index.html): browser entry · Main browser entrypoint and single-page app bootstrap. · `index.html`
- [Startup code](https://github.com/sugarlabs/musicblocks/blob/master/index.js): bootstrap · Application initialization and runtime wiring. · `index.js`
- [Activity core](https://github.com/sugarlabs/musicblocks/blob/master/js/activity.js): app state · Activity-level state, lifecycle, and browser event coordination. · `js/activity.js`
- [Workspace](https://github.com/sugarlabs/musicblocks/blob/master/js/blocks.js): block editor · Block editing, palette organization, and shared block infrastructure. · `js/blocks.js`
- [Block model](https://github.com/sugarlabs/musicblocks/blob/master/js/block.js): block infra · Core block creation, prototypes, and factory logic. · `js/block.js`
- [Block families](https://github.com/sugarlabs/musicblocks/blob/master/js/blocks/PitchBlocks.js): domain blocks · Concept-specific block sets such as pitch, rhythm, graphics, flow, and widgets. · `js/blocks/PitchBlocks.js`

### UI shell

Top-level controls, workspace chrome, and auxiliary panels.

- [Toolbar](https://github.com/sugarlabs/musicblocks/blob/master/js/toolbar.js): ui chrome · Primary app controls and top-level workspace actions. · `js/toolbar.js`
- [Palettes](https://github.com/sugarlabs/musicblocks/blob/master/js/palette.js): ui panels · Block palette, pastebox, trash, themes, language, and menu controls. · `js/palette.js`
- [Widgets](https://github.com/sugarlabs/musicblocks/blob/master/js/widgets/widgetWindows.js): aux panels · Secondary tools such as keyboard, tempo, tuner, scope, sampler, and help. · `js/widgets/widgetWindows.js`

### Runtime and output

Interpretation, turtles, audio, notation, and export paths.

- [Logo runtime](https://github.com/sugarlabs/musicblocks/blob/master/js/logo.js): interpreter · Executes block structures, resolves dependencies, and schedules actions. · `js/logo.js`
- [Turtle engine](https://github.com/sugarlabs/musicblocks/blob/master/js/turtles.js): execution runtime · Per-turtle orchestration for notes, visuals, and stateful actions. · `js/turtles.js`
- [Turtle actions](https://github.com/sugarlabs/musicblocks/blob/master/js/turtleactions/PitchActions.js): action layer · Music- and graphics-specific action handlers invoked by the runtime. · `js/turtleactions/PitchActions.js`
- [Audio stack](https://github.com/sugarlabs/musicblocks/blob/master/js/midi.js): music output · MIDI, notation, synthesis adapters, and export-friendly music utilities. · `js/midi.js`
- [JS export](https://github.com/sugarlabs/musicblocks/blob/master/js/js-export/export.js): conversion pipeline · Converts JavaScript back into block structures through AST and block generation utilities. · `js/js-export/export.js`

### Planet sharing

Optional project browsing, storage, and publishing subsystem.

- [Planet](https://github.com/sugarlabs/musicblocks/blob/master/planet/js/Planet.js): sharing subsystem · Project browsing, storage, caching, viewing, and publishing. · `planet/js/Planet.js`
- [Project storage](https://github.com/sugarlabs/musicblocks/blob/master/planet/js/ProjectStorage.js): sharing storage · Local/remote project persistence and request coordination. · `planet/js/ProjectStorage.js`

### Build and support

Localization, packaging, docs, tests, and vendored libraries.

- [Locales](https://github.com/sugarlabs/musicblocks/blob/master/locales/en.json): i18n assets · Translation files and conversion pipeline for user-facing strings. · `locales/en.json`
- [Build tools](https://github.com/sugarlabs/musicblocks/blob/master/package.json): tooling · Packaging, linting, testing, CI, and app distribution tooling. · `package.json`
- [Docs](https://github.com/sugarlabs/musicblocks/blob/master/Docs/guide/index.html): documentation · Guides, architecture notes, troubleshooting, and manuals. · `Docs/guide/index.html`
- [Vendored libs](https://github.com/sugarlabs/musicblocks/blob/master/lib/require.js): third-party assets · Bundled browser libraries, voice data, and service-worker support assets. · `lib/require.js`

## Connections

- App shell → Startup code: boots · The HTML shell loads the startup script.
- Startup code → Activity core: initializes · Startup wires the activity lifecycle and app state.
- Activity core → Toolbar: assembles · Activity code mounts top-level controls.
- Activity core → Palettes: mounts · The shell connects editing and palette controls.
- Activity core → Widgets: opens · Activity state drives auxiliary widget windows.
- Activity core → Planet: links · Activity can hand off to the sharing subsystem.
- Workspace → Block model: uses · Workspace behavior depends on the shared block model.
- Block model → Block families: organizes · Core block infrastructure instantiates the domain-specific families.
- Block families → Logo runtime: compile to · Blocks are executed through the Logo runtime.
- Logo runtime → Turtle engine: drives · Execution schedules turtle-level actions and state.
- Turtle engine → Turtle actions: dispatches · Turtle runtime invokes domain action handlers.
- Turtle actions → Audio stack: produces · Actions emit musical output and notation-facing state.
- Audio stack → Vendored libs: adapts with · Audio and playback depend on bundled browser libraries.
- Logo runtime → JS export: supports · Execution model is mirrored by the JS-to-block export path.
- Widgets → Turtle engine: inspects · Widgets share the same execution and music runtime.
- Widgets → Audio stack: controls · Several widgets manipulate synthesis and musical parameters.
- Planet → Project storage: persists · Planet coordinates storage, cache, and request management.
- Planet → Activity core: integrates · Planet is an optional UI branch connected to the main app.
- Build tools → App shell: packages · Tooling builds the browser entry and distributable assets.
- Build tools → Docs: validates · Build and CI workflows include documentation and quality checks.
- Build tools → Locales: generates · Translation conversion is part of the build pipeline.
- Docs → Workspace: describes · Documentation explains the block-based programming model.
- Vendored libs → App shell: supports · Vendored assets support the browser application shell.
