# jfo8000/scratchjr-desktop architecture

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

- Interactive diagram: https://gitdiagram.com/jfo8000/scratchjr-desktop
- Repository: https://github.com/jfo8000/scratchjr-desktop

## Overview

##### Project type and purpose
- This is a full-stack desktop application: an Electron-based port of the ScratchJr HTML5 app.
- Purpose: Host the existing ScratchJr editor (originally for iPad/Android) inside a native desktop wrapper (Windows/Mac), providing filesystem access, packaging, and small persistent storage via SQL.js.

##### File structure
- Top‐level:
- src/main.js + src/electronClient.js → Electron “main” process entry points.
- src/app/… → The entire ScratchJr HTML5/JavaScript/CSS application (shared code with mobile).
- Patterns:
- Electron’s two‐process architecture (Main vs Renderer).
- “tabletInterface” abstraction (in mobile) is replaced by ElectronDesktopInterface in renderer.
- SQL.js embedded DB for project storage.
- Assets (images, audio, SVG) delivered by the web app.
- Config & build scripts:
- package.json (npm scripts, dependencies, lint).
- forge.config.js (packaging rules).
- .travis.yml & appveyor.yml (CI builds).

##### README for additional insights
- Confirms Electron + Electron Forge for packaging.
- Describes “ElectronDesktopInterface” layer bridging HTML5 code to OS services.
- Mentions SQL.js DB with a PROJECTFILES table for embedded assets.

##### Main components
a. Native Desktop Layer (Electron Main Process)
- Responsibilities: packaging, installers, launching renderer, handling filesystem I/O, database reads/writes.
- Modules: main.js, electronClient.js.
b. Renderer / Web Layer (Electron Renderer Process)
- Hosts the ScratchJr HTML5 app (src/app/) inside a Chromium webview.
- Components:
- AppEntry / index.html / editor.html UI pages.
- Editor engine (blocks, runtime, stage, sprite modules).
- UI modules (Palette, Library, Alerts, ScriptsPane).
- Paint editor module (SVGTools, Camera, Ghost layers).
- Lobby / sample loader.
- Localization & settings.
c. ElectronDesktopInterface
- Sits in the renderer as a “third tabletInterface” implementation.
- Routes calls for filesystem & recording: either WebRTC (audio/video) or IPC to main process.
d. Database Layer (SQL.js)
- Embedded SQLite compiled to JavaScript.
- Stores projects & assets in three tables: original tables + PROJECTFILES.
- Exposed via tabletInterface → main process or direct SQL.js calls.
e. Assets & Storage
- Project files stored in SQL.js; no external FS clutter.
f. Packaging & Deployment
- Electron Forge config → produces .dmg (Mac), .exe (Windows) installers.
- CI pipelines (Travis, AppVeyor).

##### Relationships & interactions
- User clicks UI in renderer → ScratchJr JS modules → if need OS service → ElectronDesktopInterface → either Web API (WebRTC) or IPC → main process → OS FS or native dialogs.
- Renderer loads/saves project data via SQL.js library embedded in app or via main process.

##### Architectural patterns & principles
- Two-tier Electron architecture: separation of concerns between native OS boundary (main) and UI logic (renderer).
- Modular web app: editor engine, UI, paint editor, lobby.
- Abstraction layer (tabletInterface) to keep codebase portable across mobile & desktop.
- Single-page application model within editor.html.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Native Desktop Layer
    subgraph "Native Desktop Layer" 
        direction TB
        Main["main.js"]:::native
        ClientMain["electronClient.js"]:::native
    end

    %% Packaging & Deployment
    subgraph "Packaging & Deployment"
        direction TB
        ForgeConfig["forge.config.js"]:::packaging
        PackageJSON["package.json"]:::packaging
        Travis[".travis.yml"]:::packaging
        AppVeyor["appveyor.yml"]:::packaging
        Icons["src/icons/"]:::packaging
    end

    %% Renderer / Web Layer
    subgraph "Renderer / Web Layer"
        direction TB
        subgraph "App Entry Points"
            direction TB
            AppEntry["appEntry.js"]:::web
            IndexHTML["index.html"]:::web
            EditorHTML["editor.html"]:::web
            GettingStarted["gettingstarted.html"]:::web
            Home["home.html"]:::web
            InterfaceHTML["interface.html"]:::web
        end

        subgraph "Editor Engine Modules"
            direction TB
            EngineDir["src/editor/engine/"]:::web
            BlocksDir["src/editor/blocks/"]:::web
        end

        subgraph "UI Modules"
            direction TB
            UIDir["src/editor/ui/"]:::web
        end

        subgraph "Paint Editor Module"
            direction TB
            PaintEditor["src/painteditor/"]:::web
        end

        subgraph "Lobby / Sample Loader"
            direction TB
            LobbyDir["src/lobby/"]:::web
        end

        subgraph "Localization & Settings"
            direction TB
            Localizations["localizations/"]:::web
            SettingsFile["settings.json"]:::web
        end

        subgraph "Assets & SQL.js"
            direction TB
            Assets["assets/"]:::web
            PNGLib["pnglibrary/"]:::web
            SVGLib["svglibrary/"]:::web
            SQLLib["assets/lib/"]:::storage
        end

        EDI["ElectronDesktopInterface"]:::web
    end

    %% Storage Layer
    SQLDB["SQL.js DB Engine"]:::storage

    %% External APIs
    subgraph "External APIs"
        direction TB
        WebRTC["WebRTC API"]:::external
        OSFS["OS FileSystem"]:::external
        NativeDialogs["Native Dialogs"]:::external
    end

    %% Connections
    %% Renderer to Interface to Main
    EDI -->|"IPC"| Main
    EDI -->|"IPC"| ClientMain
    AppEntry --> EDI
    EngineDir --> EDI
    UIDir --> EDI

    %% Renderer direct to SQL.js
    AppEntry -->|"SQL query"| SQLLib
    EngineDir -->|"SQL query"| SQLLib

    %% Main to OS FS and Native Dialogs
    Main -->|"file read/write"| OSFS
    Main -->|"dialog"| NativeDialogs

    %% Interface to WebRTC
    EDI -->|"media capture"| WebRTC

    %% SQL.js DB Engine usage
    SQLLib --> SQLDB

    %% Packaging pipeline
    PackageJSON --> ForgeConfig
    ForgeConfig --> Icons
    ForgeConfig --> Travis
    ForgeConfig --> AppVeyor

    %% Click Events
    click Main "https://github.com/jfo8000/scratchjr-desktop/blob/master/src/main.js"
    click ClientMain "https://github.com/jfo8000/scratchjr-desktop/blob/master/src/electronClient.js"
    click ForgeConfig "https://github.com/jfo8000/scratchjr-desktop/blob/master/forge.config.js"
    click PackageJSON "https://github.com/jfo8000/scratchjr-desktop/blob/master/package.json"
    click Travis "https://github.com/jfo8000/scratchjr-desktop/blob/master/.travis.yml"
    click AppVeyor "https://github.com/jfo8000/scratchjr-desktop/blob/master/appveyor.yml"
    click Icons "https://github.com/jfo8000/scratchjr-desktop/tree/master/src/icons/"
    click AppEntry "https://github.com/jfo8000/scratchjr-desktop/blob/master/src/app/appEntry.js"
    click IndexHTML "https://github.com/jfo8000/scratchjr-desktop/blob/master/src/app/index.html"
    click EditorHTML "https://github.com/jfo8000/scratchjr-desktop/blob/master/src/app/editor.html"
    click GettingStarted "https://github.com/jfo8000/scratchjr-desktop/blob/master/src/app/gettingstarted.html"
    click Home "https://github.com/jfo8000/scratchjr-desktop/blob/master/src/app/home.html"
    click InterfaceHTML "https://github.com/jfo8000/scratchjr-desktop/blob/master/src/app/inapp/interface.html"
    click EngineDir "https://github.com/jfo8000/scratchjr-desktop/tree/master/src/app/src/editor/engine/"
    click BlocksDir "https://github.com/jfo8000/scratchjr-desktop/tree/master/src/app/src/editor/blocks/"
    click UIDir "https://github.com/jfo8000/scratchjr-desktop/tree/master/src/app/src/editor/ui/"
    click PaintEditor "https://github.com/jfo8000/scratchjr-desktop/tree/master/src/app/src/painteditor/"
    click LobbyDir "https://github.com/jfo8000/scratchjr-desktop/tree/master/src/app/src/lobby/"
    click Localizations "https://github.com/jfo8000/scratchjr-desktop/tree/master/src/app/localizations/"
    click SettingsFile "https://github.com/jfo8000/scratchjr-desktop/blob/master/src/app/settings.json"
    click SQLLib "https://github.com/jfo8000/scratchjr-desktop/tree/master/src/app/assets/lib/"
    click Assets "https://github.com/jfo8000/scratchjr-desktop/tree/master/src/app/assets/"
    click PNGLib "https://github.com/jfo8000/scratchjr-desktop/tree/master/src/app/pnglibrary/"
    click SVGLib "https://github.com/jfo8000/scratchjr-desktop/tree/master/src/app/svglibrary/"

    %% Styles
    classDef native fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef web fill:#90EE90,stroke:#333,stroke-width:1px
    classDef storage fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef packaging fill:#EEEEEE,stroke:#333,stroke-width:1px
```
