# openblockcc/openblock-desktop architecture

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

- Interactive diagram: https://gitdiagram.com/openblockcc/openblock-desktop
- Repository: https://github.com/openblockcc/openblock-desktop

## Overview

##### Project Type & Purpose
- This is a full‑stack desktop application built on Electron. It has two runtime processes (a Node.js “main” process and a Chromium “renderer” process), plus a build/packaging pipeline driven by webpack, electron-builder, and helper scripts.

- Top‑level build & config:
- webpack.main.js, webpack.renderer.js, webpack.makeConfig.js
- scripts/ (download drivers, post‑sign hooks, builder wrappers)
- Runtime code:
- src/main/ – all main‑process modules (index, argv, FileFilters, MacOSMenu, Updater, TelemetryClient)
- src/renderer/ – React UI code (app.jsx, HOCs, individual pages, CSS, index.html)
- src/common/ – shared utilities (ElectronStorageHelper, logging)
- Dev and CI:
- .github/workflows/ – build & release, build test app
- .eslintrc.js, .editorconfig, package.json

##### README for Architectural Clues
- Confirms Electron + React stack
- Mentions distribution via GitHub Actions & electron-builder
- Screenshots in doc/ suggest two GUI states (loading, app, about, license, privacy)

a. Build & Packaging Pipeline
- Source files → webpack (main + renderer) → electron-builder → platform‑specific installers (buildResources → packaged output)
- Helper scripts invoked before/after signing or to fetch driver assets
b. Electron Main Process (src/main)
- Entry: argv.js → index.js
- Modules: FileFilters, MacOSMenu, OpenblockDesktopLink, Updater, TelemetryClient
- Communicates with file system (via ElectronStorageHelper) and external services (update server, telemetry endpoint)
- Listens on IPC channels for UI requests
c. Electron Renderer Process (src/renderer)
- React components wrapped by HOCs (ScratchDesktopAppStateHOC, ScratchDesktopGUIHOC)
- Pages: loading, about, license, privacy, main app
- Sends/receives IPC messages to main process
d. Shared/Common Modules (src/common)
- Logging (log.js)
- Storage helper for persistent settings/data
e. External Services & Data Stores
- Telemetry server (HTTPS)
- Auto‑update server (HTTPS)

##### Architectural Patterns & Design Principles
- Process separation: main vs renderer → clear security/sandbox boundary
- HOCs in React promote code reuse (state, telemetry instrumentation)
- Modular services in main process (updater, telemetry)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CI/CD & Dev Config
    subgraph "CI/CD & Dev Config"
        direction TB
        CI1[".github/workflows/build-and-release.yml"]:::ci
        CI2[".github/workflows/build-test-app.yml"]:::ci
        CI3[".eslintrc.js"]:::ci
        CI4[".editorconfig"]:::ci
        CI5["package.json"]:::ci
    end

    %% Build & Packaging Pipeline
    subgraph "Build & Packaging Pipeline"
        direction TB
        WP1["webpack.main.js"]:::build
        WP2["webpack.renderer.js"]:::build
        WP3["webpack.makeConfig.js"]:::build
        EB["electron-builder.yaml"]:::build
        BR[/buildResources/]:::static
        SCR[/scripts/]:::build
        PACK["Packaged Installers"]:::static
    end

    %% Runtime Processes
    subgraph "Runtime"
        direction LR
        subgraph "Electron Main Process"
            direction TB
            M1["src/main/argv.js"]:::main
            M2["src/main/index.js"]:::main
            M3["src/main/FileFilters.js"]:::main
            M4["src/main/MacOSMenu.js"]:::main
            M5["src/main/OpenblockDesktopLink.js"]:::main
            M6["src/main/OpenblockDesktopUpdater.js"]:::main
            M7["src/main/OpenblockDesktopTelemetry.js"]:::main
            M8["src/main/telemetry/TelemetryClient.js"]:::main
        end
        subgraph "Electron Renderer Process"
            direction TB
            R1["src/renderer/index.html"]:::renderer
            R2["src/renderer/index.js"]:::renderer
            R3["src/renderer/app.jsx"]:::renderer
            R4["src/renderer/app.css"]:::renderer
            R5["src/renderer/ScratchDesktopAppStateHOC.jsx"]:::renderer
            R6["src/renderer/ScratchDesktopGUIHOC.jsx"]:::renderer
            R7["src/renderer/loading.jsx"]:::renderer
            R8["src/renderer/loading.css"]:::renderer
            R9["src/renderer/about.jsx"]:::renderer
            R10["src/renderer/about.css"]:::renderer
            R11["src/renderer/license.jsx"]:::renderer
            R12["src/renderer/license.css"]:::renderer
            R13["src/renderer/privacy.jsx"]:::renderer
            R14["src/renderer/privacy.css"]:::renderer
            R15["src/renderer/showPrivacyPolicy.js"]:::renderer
        end
    end

    %% Shared / Common Modules
    subgraph "Shared / Common Modules"
        direction TB
        C1["src/common/ElectronStorageHelper.js"]:::common
        C2["src/common/log.js"]:::common
        Store[(Local JSON Store)]:::storage
    end

    %% External Services
    TelemetryServer((Telemetry Server)):::external
    UpdateServer((Auto-update Server)):::external

    %% Connections
    CI1 -->|triggers| WP1
    CI1 -->|triggers| WP2
    CI1 -->|triggers| WP3
    CI2 -->|triggers| WP1
    CI2 -->|triggers| WP2
    CI2 -->|triggers| WP3

    WP1 -.->|"bundle main" | EB
    WP2 -.->|"bundle renderer"| EB
    EB -->|"packaging"| BR
    EB -->|"packaging"| SCR
    EB -->|"output"| PACK

    M1 --> M2
    M2 --> M3
    M2 --> M4
    M2 --> M5
    M2 --> M6
    M2 --> M7
    M7 --> M8
    M3 --> C1
    M7 --> TelemetryServer
    M6 --> UpdateServer

    R2 --> R3
    R3 --> R4
    R3 --> R5
    R5 --> R6
    R3 --> R7
    R7 --> R8
    R3 --> R9
    R9 --> R10
    R3 --> R11
    R11 --> R12
    R3 --> R13
    R13 --> R14
    R3 --> R15

    M2 <-->|"IPC Channels"| R2

    C1 --> Store
    C2 --> M2
    C2 --> R2

    %% Click Events
    click CI1 "https://github.com/openblockcc/openblock-desktop/blob/main/.github/workflows/build-and-release.yml"
    click CI2 "https://github.com/openblockcc/openblock-desktop/blob/main/.github/workflows/build-test-app.yml"
    click CI3 "https://github.com/openblockcc/openblock-desktop/blob/main/.eslintrc.js"
    click CI4 "https://github.com/openblockcc/openblock-desktop/blob/main/.editorconfig"
    click CI5 "https://github.com/openblockcc/openblock-desktop/blob/main/package.json"

    click WP1 "https://github.com/openblockcc/openblock-desktop/blob/main/webpack.main.js"
    click WP2 "https://github.com/openblockcc/openblock-desktop/blob/main/webpack.renderer.js"
    click WP3 "https://github.com/openblockcc/openblock-desktop/blob/main/webpack.makeConfig.js"
    click EB "https://github.com/openblockcc/openblock-desktop/blob/main/electron-builder.yaml"
    click BR "https://github.com/openblockcc/openblock-desktop/tree/main/buildResources/"
    click SCR "https://github.com/openblockcc/openblock-desktop/tree/main/scripts/"

    click M1 "https://github.com/openblockcc/openblock-desktop/blob/main/src/main/argv.js"
    click M2 "https://github.com/openblockcc/openblock-desktop/blob/main/src/main/index.js"
    click M3 "https://github.com/openblockcc/openblock-desktop/blob/main/src/main/FileFilters.js"
    click M4 "https://github.com/openblockcc/openblock-desktop/blob/main/src/main/MacOSMenu.js"
    click M5 "https://github.com/openblockcc/openblock-desktop/blob/main/src/main/OpenblockDesktopLink.js"
    click M6 "https://github.com/openblockcc/openblock-desktop/blob/main/src/main/OpenblockDesktopUpdater.js"
    click M7 "https://github.com/openblockcc/openblock-desktop/blob/main/src/main/OpenblockDesktopTelemetry.js"
    click M8 "https://github.com/openblockcc/openblock-desktop/blob/main/src/main/telemetry/TelemetryClient.js"

    click R1 "https://github.com/openblockcc/openblock-desktop/blob/main/src/renderer/index.html"
    click R2 "https://github.com/openblockcc/openblock-desktop/blob/main/src/renderer/index.js"
    click R3 "https://github.com/openblockcc/openblock-desktop/blob/main/src/renderer/app.jsx"
    click R4 "https://github.com/openblockcc/openblock-desktop/blob/main/src/renderer/app.css"
    click R5 "https://github.com/openblockcc/openblock-desktop/blob/main/src/renderer/ScratchDesktopAppStateHOC.jsx"
    click R6 "https://github.com/openblockcc/openblock-desktop/blob/main/src/renderer/ScratchDesktopGUIHOC.jsx"
    click R7 "https://github.com/openblockcc/openblock-desktop/blob/main/src/renderer/loading.jsx"
    click R8 "https://github.com/openblockcc/openblock-desktop/blob/main/src/renderer/loading.css"
    click R9 "https://github.com/openblockcc/openblock-desktop/blob/main/src/renderer/about.jsx"
    click R10 "https://github.com/openblockcc/openblock-desktop/blob/main/src/renderer/about.css"
    click R11 "https://github.com/openblockcc/openblock-desktop/blob/main/src/renderer/license.jsx"
    click R12 "https://github.com/openblockcc/openblock-desktop/blob/main/src/renderer/license.css"
    click R13 "https://github.com/openblockcc/openblock-desktop/blob/main/src/renderer/privacy.jsx"
    click R14 "https://github.com/openblockcc/openblock-desktop/blob/main/src/renderer/privacy.css"
    click R15 "https://github.com/openblockcc/openblock-desktop/blob/main/src/renderer/showPrivacyPolicy.js"

    click C1 "https://github.com/openblockcc/openblock-desktop/blob/main/src/common/ElectronStorageHelper.js"
    click C2 "https://github.com/openblockcc/openblock-desktop/blob/main/src/common/log.js"

    %% Styles
    classDef ci fill:#f2f2f2,stroke:#999,stroke-width:1px
    classDef build fill:#e6e6e6,stroke:#666,stroke-width:1px
    classDef main fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef renderer fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef common fill:#f8f9fa,stroke:#6c757d,stroke-width:1px
    classDef storage fill:#fff2cc,stroke:#e6b800,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef static fill:#f0f0f0,stroke:#999,stroke-width:1px
```
