# scratchfoundation/scratch-vm architecture

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

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

## Overview

##### Main Components

a. Core Runtime Layer:
- Virtual Machine (src/virtual-machine.js)
- Runtime Engine (src/engine/runtime.js)
- Thread Execution System (src/engine/thread.js, src/engine/sequencer.js)
- Blocks Execution Engine (src/engine/blocks.js)

b. Extension System:
- Extension Manager (src/extension-support/extension-manager.js)
- Extension Worker Infrastructure (src/extension-support/extension-worker.js)
- Built-in Extensions (src/extensions/*)

c. I/O System:
- Device I/O (BLE, Bluetooth, Video, etc.)
- User Input (Keyboard, Mouse, etc.)
- Cloud Data Handling

d. Block Implementation Layer:
- Core Blocks (Motion, Looks, Sound, etc.)
- Custom Block Support
- Block Utilities

##### Architectural Relationships

**┌─────────────────────────────────────────────────────┐**
- Scratch Blocks UI                   │
- ┬───────────────────────────────────┘

**┌─────────────────▼───────────────────────────────────┐**
- Virtual Machine                        │
- ┤
- ┌─────────────┐    ┌──────────────┐  ┌──────────┐  │
- Runtime   │◄─►│Thread Manager │◄─►│ Blocks   │  │
- ┘    └──────────────┘  └──────────┘  │
- ▲                  ▲              ▲         │
- ┼──────────────────┼──────────────┼─────────┤
- ┌───────▼──────┐    ┌──────▼─────┐  ┌────▼─────┐   │
- Extensions  │    │ I/O System │  │Serializer │   │
- ┘    └────────────┘  └──────────┘   │
- ┘

##### Important Architectural Patterns to Highlight

a. Event-Driven Architecture:
- How block events flow from the UI through the VM
- Event dispatch system

b. Worker Architecture:
- Demonstrate the separation between main thread and extension workers
- Communication channels between components

c. Plugin System:
- How extensions are loaded and integrated
- Extension API interface

##### Additional Elements

- Notes for key architectural decisions
- Version compatibility interfaces (SB2/SB3)
- External dependencies and interfaces

##### Implementation Details to Consider

- Block execution pipeline
- Thread scheduling system
- Demonstrate asset loading and management
- How the VM interfaces with the Scratch Blocks UI

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph UI[Scratch Blocks UI]
        ScratchUI[Scratch Blocks Interface]
    end

    subgraph VM[Virtual Machine Core]
        VirtualMachine["Virtual Machine"]:::core
        Runtime["Runtime Engine"]:::core
        ThreadManager["Thread Manager"]:::core
        BlocksEngine["Blocks Engine"]:::core
    end

    subgraph Extensions[Extension System]
        ExtManager["Extension Manager"]:::extension
        ExtWorker["Extension Worker"]:::extension
        BuiltInExt["Built-in Extensions"]:::extension
    end

    subgraph IO[I/O System]
        BLE["BLE Interface"]:::io
        BT["Bluetooth Interface"]:::io
        Keyboard["Keyboard Input"]:::io
        Mouse["Mouse Input"]:::io
        Cloud["Cloud Data"]:::io
        Video["Video System"]:::io
    end

    subgraph Blocks[Block Implementation]
        CoreBlocks["Core Blocks"]:::block
        BlockUtils["Block Utilities"]:::block
        direction TB
        subgraph BlockTypes[Block Categories]
            Control["Control Blocks"]:::block
            Motion["Motion Blocks"]:::block
            Looks["Looks Blocks"]:::block
            Sound["Sound Blocks"]:::block
            Events["Event Blocks"]:::block
            Operators["Operator Blocks"]:::block
            Sensing["Sensing Blocks"]:::block
            Data["Data Blocks"]:::block
            Procedures["Procedure Blocks"]:::block
        end
    end

    %% Relationships
    ScratchUI --> VirtualMachine
    VirtualMachine <--> Runtime
    Runtime <--> ThreadManager
    ThreadManager <--> BlocksEngine
    BlocksEngine <--> BlockUtils
    VirtualMachine <--> ExtManager
    ExtManager <--> ExtWorker
    ExtWorker <--> BuiltInExt
    Runtime <--> IO
    BlocksEngine <--> CoreBlocks
    CoreBlocks --- BlockTypes

    %% Click Events
    click VirtualMachine "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/virtual-machine.js"
    click Runtime "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/engine/runtime.js"
    click ThreadManager "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/engine/thread.js"
    click BlocksEngine "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/engine/blocks.js"
    click ExtManager "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/extension-support/extension-manager.js"
    click ExtWorker "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/extension-support/extension-worker.js"
    click BuiltInExt "https://github.com/scratchfoundation/scratch-vm/tree/develop/src/extensions"
    click BLE "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/io/ble.js"
    click BT "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/io/bt.js"
    click Keyboard "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/io/keyboard.js"
    click Mouse "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/io/mouse.js"
    click Cloud "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/io/cloud.js"
    click Video "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/io/video.js"
    click Control "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/blocks/scratch3_control.js"
    click Motion "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/blocks/scratch3_motion.js"
    click Looks "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/blocks/scratch3_looks.js"
    click Sound "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/blocks/scratch3_sound.js"
    click Events "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/blocks/scratch3_event.js"
    click Operators "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/blocks/scratch3_operators.js"
    click Sensing "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/blocks/scratch3_sensing.js"
    click Data "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/blocks/scratch3_data.js"
    click Procedures "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/blocks/scratch3_procedures.js"
    click BlockUtils "https://github.com/scratchfoundation/scratch-vm/blob/develop/src/engine/block-utility.js"

    %% Styling
    classDef core fill:#2374ab
    classDef extension fill:#57a773
    classDef io fill:#ff8c42
    classDef block fill:#984447
    
    %% Legend
    subgraph Legend
        CoreComp["Core Components"]:::core
        ExtComp["Extension Components"]:::extension
        IOComp["I/O Components"]:::io
        BlockComp["Block Components"]:::block
    end
```
