# eurekascratch/eureka architecture

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

- Interactive diagram: https://gitdiagram.com/eurekascratch/eureka
- Repository: https://github.com/eurekascratch/eureka

## Overview

##### Project type and purpose
- Eureka is a userscript project whose goal is to sideload and manage third-party extensions in Scratch-based editors. It also provides a built-in React-based dashboard for managing those extensions at runtime in the browser.

##### File structure
- Top-level config & CI files: .github/, jest.config.mjs, rollup.config.mjs, babel.config.cjs, tsconfig.json, pnpm-lock.yaml
- Source code: src/main/ – the core runtime; subfolders:
- dashboard/ – React app (app.tsx, CSS, assets) that renders the UI
- middleware/ – pipeline for loading extensions (extension-metadata, indexing)
- patches/ – code that applies hooks/patches into Scratch internals
- trap/ – trap modules to intercept and adapt VM/blocks APIs
- ctx.ts – shared runtime context object
- index.ts & meta.js – userscript bootstrap and metadata
- Types: src/types/ – TypeScript definitions for CSS, VM, global and SVG
- Tests: tests/ – automated tests via Jest

##### README for additional insights
- Eureka’s core functionality:
- Inject itself via UserScript Manager (Tampermonkey)
- Detect Scratch editors on the page
- Hook into the Scratch VM or Blocks API
- Provide an extended extension-loading API
- Expose a React dashboard for end users
- Supported platforms table shows how it integrates with different Scratch forks

a. Main components
1. Userscript injector (Tampermonkey/Violentmonkey)
2. Bootstrap / entry point (src/main/index.ts + meta.js)
3. Runtime context object (ctx.ts)
4. Middleware pipeline (middleware/)
5. Patcher engine (patches/)
6. Trap modules (trap/) – VM/Blocks adapters
7. Utility services (util/) – logging, settings, localization, injection helpers
8. Extension loader API (exposed for 3rd-party extensions)
9. Dashboard UI (React app under dashboard/) served as an overlay or panel
10. External Scratch editor environment (VM, Blocks workspace)
11. User settings storage (localStorage or internal store)
12. Tests suite (Jest) – peripheral

b. Relationships & data flow
- The Userscript injector adds the Eureka bundle into the page
- Bootstrap initializes ctx, then runs middleware in sequence:
→ extension-metadata middleware reads 3rd-party manifest
- Patcher engine applies code patches to the Scratch VM/Blocks
- Trap modules intercept API calls (e.g., block creation, VM execution)
- Utility modules provide services (i18n, settings, console capture)
- Dashboard UI connects to ctx to read settings, list loaded extensions, toggle them
- The Extension loader API allows 3rd-party scripts to call ctx.loadExtension(...)
- All interactions occur in the browser environment, no backend

c. Architectural patterns & design principles
- Modular pipeline (middleware)
- Plugin architecture: clear extension points
- Separation of concerns: injector / patcher / trap / dashboard / utils
- Single‐page overlay for UI (React)
- TypeScript for type safety, Rollup for bundling

d. Key technologies/frameworks
- TypeScript
- React & JSX (dashboard)
- Rollup & Babel (build pipeline)
- Jest (testing)
- PNPM (package management)
- UserScript metadata (Tampermonkey)

##### Final advice
- Be very detailed: represent each folder/major module as a component

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    USR_INJ["Userscript Injector"]:::external
    SCRATCH_VM["Scratch VM/Blocks"]:::external
    LOCAL_STORAGE["localStorage"]:::external

    %% Core Runtime Modules
    subgraph "Core Runtime" 
        BOOT["Bootstrap / Entry Point"]:::core
        CTX["Runtime Context (ctx)"]:::core
        subgraph "Middleware Pipeline" 
            MW["Middleware Index"]:::core
            MW_EM["Extension Metadata"]:::core
        end
        subgraph "Patcher Engine"
            PATCH_APPLY["applier.ts"]:::core
            PATCH_TOOL["toolbox-stuffs.ts"]:::core
        end
        subgraph "Trap Modules"
            TRAP_BL["blocks.ts"]:::core
            TRAP_RD["redux.ts"]:::core
            TRAP_VM["vm.ts"]:::core
        end
        EXT_API["Extension Loader API"]:::core
    end

    %% Utilities
    subgraph "Utility Services"
        UTIL_CAST["cast.ts"]:::util
        UTIL_COLOR["color.ts"]:::util
        UTIL_CONSOLE["console.ts"]:::util
        UTIL_INJECT["inject.ts"]:::util
        UTIL_L10N["l10n.ts"]:::util
        UTIL_FMT["maybe-format-message.ts"]:::util
        UTIL_SETTINGS["settings.ts"]:::util
        UTIL_XML["xml-escape.ts"]:::util
    end

    %% UI Layer
    subgraph "Dashboard UI" 
        DASH_APP["app.tsx"]:::ui
        DASH_NORM["normalize.css"]:::ui
        DASH_STYLE["style.css"]:::ui
        DASH_MOD["style.module.css"]:::ui
        DASH_ASSETS["assets/"]:::ui
    end

    %% Types & Localization & Tests
    subgraph "Types & Localization & Tests"
        TYPES_CSS["css.d.ts"]:::util
        TYPES_DUCK["ducktypes.d.ts"]:::util
        TYPES_GLOBAL["global.d.ts"]:::util
        TYPES_SVG["svg.d.ts"]:::util
        TYPES_VM["vm.d.ts"]:::util
        LOCALE_EN["en.json"]:::util
        LOCALE_ZH["zh-cn.json"]:::util
        TEST_E["eureka.test.ts"]:::util
        TEST_SET["setup.ts"]:::util
    end

    %% Data Flow
    USR_INJ -->|"injects bundle"| BOOT
    BOOT -->|"init ctx"| CTX
    CTX -->|"run pipeline"| MW
    MW -->|"use metadata"| MW_EM
    MW -->|"invoke patches"| PATCH_APPLY
    PATCH_APPLY -->|"applyPatch"| PATCH_TOOL
    PATCH_TOOL -->|"patch VM"| TRAP_BL
    TRAP_BL -->|"interceptCall"| TRAP_RD
    TRAP_RD -->|"interceptCall"| TRAP_VM
    TRAP_VM -->|"forward to"| SCRATCH_VM
    CTX -->|"expose"| EXT_API
    EXT_API -->|"loadExtension"| MW
    CTX -->|"settings access"| UTIL_SETTINGS
    UTIL_SETTINGS -->|"persist"| LOCAL_STORAGE
    DASH_APP -->|"render UI"| CTX
    CTX -->|"provide data"| DASH_APP

    %% Utilities to Core
    UTIL_CAST --> BOOT
    UTIL_COLOR --> BOOT
    UTIL_CONSOLE --> BOOT
    UTIL_INJECT --> BOOT
    UTIL_L10N --> BOOT
    UTIL_FMT --> BOOT
    UTIL_SETTINGS --> BOOT
    UTIL_XML --> BOOT

    %% Styles
    classDef core fill:#D0E6FF,stroke:#0366d6
    classDef ui fill:#DFFFE0,stroke:#28a745
    classDef external fill:#FFE6B3,stroke:#d69e00
    classDef util fill:#E0E0E0,stroke:#666

    %% Click Events
    click USR_INJ "https://github.com/eurekascratch/eureka/blob/trunk/src/main/meta.js"
    click BOOT "https://github.com/eurekascratch/eureka/blob/trunk/src/main/index.ts"
    click CTX "https://github.com/eurekascratch/eureka/blob/trunk/src/main/ctx.ts"
    click MW "https://github.com/eurekascratch/eureka/blob/trunk/src/main/middleware/index.ts"
    click MW_EM "https://github.com/eurekascratch/eureka/blob/trunk/src/main/middleware/extension-metadata.ts"
    click PATCH_APPLY "https://github.com/eurekascratch/eureka/blob/trunk/src/main/patches/applier.ts"
    click PATCH_TOOL "https://github.com/eurekascratch/eureka/blob/trunk/src/main/patches/toolbox-stuffs.ts"
    click TRAP_BL "https://github.com/eurekascratch/eureka/blob/trunk/src/main/trap/blocks.ts"
    click TRAP_RD "https://github.com/eurekascratch/eureka/blob/trunk/src/main/trap/redux.ts"
    click TRAP_VM "https://github.com/eurekascratch/eureka/blob/trunk/src/main/trap/vm.ts"
    click UTIL_CAST "https://github.com/eurekascratch/eureka/blob/trunk/src/main/util/cast.ts"
    click UTIL_COLOR "https://github.com/eurekascratch/eureka/blob/trunk/src/main/util/color.ts"
    click UTIL_CONSOLE "https://github.com/eurekascratch/eureka/blob/trunk/src/main/util/console.ts"
    click UTIL_INJECT "https://github.com/eurekascratch/eureka/blob/trunk/src/main/util/inject.ts"
    click UTIL_L10N "https://github.com/eurekascratch/eureka/blob/trunk/src/main/util/l10n.ts"
    click UTIL_FMT "https://github.com/eurekascratch/eureka/blob/trunk/src/main/util/maybe-format-message.ts"
    click UTIL_SETTINGS "https://github.com/eurekascratch/eureka/blob/trunk/src/main/util/settings.ts"
    click UTIL_XML "https://github.com/eurekascratch/eureka/blob/trunk/src/main/util/xml-escape.ts"
    click DASH_APP "https://github.com/eurekascratch/eureka/blob/trunk/src/main/dashboard/app.tsx"
    click DASH_NORM "https://github.com/eurekascratch/eureka/blob/trunk/src/main/dashboard/normalize.css"
    click DASH_STYLE "https://github.com/eurekascratch/eureka/blob/trunk/src/main/dashboard/style.css"
    click DASH_MOD "https://github.com/eurekascratch/eureka/blob/trunk/src/main/dashboard/style.module.css"
    click DASH_ASSETS "https://github.com/eurekascratch/eureka/tree/trunk/src/main/dashboard/assets/"
    click TYPES_CSS "https://github.com/eurekascratch/eureka/blob/trunk/src/types/css.d.ts"
    click TYPES_DUCK "https://github.com/eurekascratch/eureka/blob/trunk/src/types/ducktypes.d.ts"
    click TYPES_GLOBAL "https://github.com/eurekascratch/eureka/blob/trunk/src/types/global.d.ts"
    click TYPES_SVG "https://github.com/eurekascratch/eureka/blob/trunk/src/types/svg.d.ts"
    click TYPES_VM "https://github.com/eurekascratch/eureka/blob/trunk/src/types/vm.d.ts"
    click LOCALE_EN "https://github.com/eurekascratch/eureka/blob/trunk/locales/en.json"
    click LOCALE_ZH "https://github.com/eurekascratch/eureka/blob/trunk/locales/zh-cn.json"
    click TEST_E "https://github.com/eurekascratch/eureka/blob/trunk/tests/eureka.test.ts"
    click TEST_SET "https://github.com/eurekascratch/eureka/blob/trunk/tests/setup.ts"
```
