# electron/fiddle architecture

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

- Interactive diagram: https://gitdiagram.com/electron/fiddle
- Repository: https://github.com/electron/fiddle

## Overview

##### Project Type and Purpose
- This is an Electron desktop application ("Electron Fiddle") that lets users write, run, save, and package small Electron experiments.
- It combines a “backend” (the Electron Main process), a “frontend” (the Electron Renderer process built with React/Monaco), a secure Preload bridge, external runner processes, and integrations with NPM & GitHub.

##### Out Top-Level Components
A. Main Process (src/main)
– Manages application lifecycle, menus, dialogs (about-panel.ts, menu.ts, dialogs.ts).
– Handles file I/O, templates (templates.ts), first-run checks, version management (versions.ts), update logic (squirrel.ts, update.ts), Sentry error reporting (sentry.ts), and command-line flags.
– Talks to external services: NPM registry (npm.ts), GitHub Gist via Octokit, Electron releases (fetch-releases tool).
B. Preload Bridge (src/preload/preload.ts)
– Exposes a secure, limited API surface to the Renderer over IPC channels defined in ipc-events.ts.
– Functions include read/write fiddle, fetch versions, run code, open external links.
C. Renderer Process (src/renderer + src/less)
– React + TypeScript UI using Monaco Editor.
– Components for file tree, package manager, version selector, editors, outputs, settings, tours, etc.
– State management (state.ts), task runner (task-runner.ts), runner control (runner.ts), remote loader for user code.
– Communicates with Main via IPC.

##### “External Runner” Process
– When the user clicks “Run,” Main/Renderer spawn a separate Electron child‐process to execute the user’s fiddle.

##### External Services
- NPM Registry
- GitHub Gist / API (via Octokit)
- Electron Releases (GitHub)
- Sentry (error reporting)

##### Build/Tooling (outside “Electron App”)
- Webpack configs (tools/webpack/…), which bundle main, renderer, and preload.
- Forge config (forge.config.ts) for packaging.
- CI/CD flows (.circleci, GitHub workflows).

##### Architectural Patterns
- Multi-process separation (Main vs Renderer vs Runner).
- IPC-based communication, with a Preload context for secure channels.
- Modular code organization: src/main/utils, src/renderer/utils, src/less for theming.
- Packaging via electron-forge + Squirrel auto-updater.

##### Final Checklist
– Main process modules: lifecycle, menus, file I/O, updates, network.
– Preload: secure IPC API.
– Renderer: React UI, state, task runner, Monaco editor.
– Electron Runner: user-code execution sandbox.
– External services: NPM, GitHub, Sentry, update server.
– Build/tooling: Webpack, Forge, CI pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Electron App Container
    subgraph "Electron App"
        direction TB

        %% Main Process
        subgraph "Main Process (src/main)" 
            direction TB
            MP_Main["main.ts"]:::main
            MP_Menu["menu.ts"]:::main
            MP_Dialogs["dialogs.ts"]:::main
            MP_About["about-panel.ts"]:::main
            MP_CLI["command-line.ts"]:::main
            MP_FirstRun["first-run.ts"]:::main
            MP_Files["files.ts"]:::main
            MP_Templates["templates.ts"]:::main
            MP_Versions["versions.ts"]:::main
            MP_Update["update.ts"]:::main
            MP_Squirrel["squirrel.ts"]:::main
            MP_NPM["npm.ts"]:::main
            MP_SentryMain["sentry.ts"]:::main
            MP_IPC["ipc.ts"]:::main

            subgraph "Utils"
                direction TB
                MP_CheckFirstRun["check-first-run.ts"]:::main
                MP_Exec["exec.ts"]:::main
                MP_GetFiles["get-files.ts"]:::main
                MP_ReadFiddle["read-fiddle.ts"]:::main
            end
        end

        %% Preload Bridge
        subgraph "Preload Bridge (src/preload)"
            direction TB
            PB_Preload["preload.ts"]:::preload
            PB_IPCEvents["ipc-events.ts"]:::preload
        end

        %% Renderer Process
        subgraph "Renderer (src/renderer + src/less)"
            direction TB
            R_App["app.tsx"]:::renderer
            R_Main["main.tsx"]:::renderer
            R_State["state.ts"]:::renderer
            R_TaskRunner["task-runner.ts"]:::renderer
            R_Runner["runner.ts"]:::renderer
            R_RemoteLoader["remote-loader.ts"]:::renderer

            subgraph "Components"
                direction TB
                RC_FileTree["sidebar-file-tree.tsx"]:::renderer
                RC_PkgManager["sidebar-package-manager.tsx"]:::renderer
                RC_VersionChooser["commands-version-chooser.tsx"]:::renderer
                RC_VersionSelect["version-select.tsx"]:::renderer
                RC_Editor["editor.tsx"]:::renderer
                RC_EditorsToolbar["editors-toolbar-button.tsx"]:::renderer
                RC_Output["output.tsx"]:::renderer
                RC_Settings["settings-general.tsx"]:::renderer
                RC_Tour["tour.tsx"]:::renderer
                RC_TourWelcome["tour-welcome.tsx"]:::renderer
            end

            R_Styling["less styles"]:::renderer
        end
    end

    %% External Runner Process
    ER["Electron Runner"]:::external

    %% External Services
    subgraph "External Services"
        direction TB
        ES_NPM["NPM Registry"]:::service
        ES_GitHub["GitHub Gist/API"]:::service
        ES_Releases["Electron Releases"]:::service
        ES_SentryRenderer["Sentry (Renderer)"]:::service
        ES_SentryMain2["Sentry (Main)"]:::service
        ES_AutoUpdate["Auto-Updater"]:::service
    end

    %% Build / Tooling
    subgraph "Build & Tooling"
        direction TB
        BT_WebpackMain["webpack.main.config.ts"]:::build
        BT_WebpackRenderer["webpack.renderer.config.ts"]:::build
        BT_Forge["forge.config.ts"]:::build
        BT_CI_Circle[".circleci/config.yml"]:::build
        BT_CI_GH[".github/workflows"]:::build
    end

    %% Relationships
    R_App -->|"calls UI init"| R_Main
    R_Main -->|"IPC read/write/run"| PB_Preload
    PB_Preload -->|"forwards IPC"| MP_IPC

    MP_IPC --> MP_ReadFiddle
    MP_IPC --> MP_CheckFirstRun
    MP_IPC --> MP_Exec

    MP_Main --> ES_NPM
    MP_Main --> ES_GitHub
    MP_Main --> ES_SentryMain2
    MP_Main --> ES_AutoUpdate

    R_Runner --> ER
    ER -->|"stdout/stderr"| RC_Output

    %% Build flows
    BT_WebpackMain -.->|"bundles main"| MP_Main
    BT_WebpackRenderer -.->|"bundles renderer"| R_App
    BT_Forge -.->|"packages app"| ElectronApp

    %% Classes
    classDef main fill:#FFCC00,stroke:#333,stroke-width:1px
    classDef preload fill:#00CCFF,stroke:#333,stroke-width:1px
    classDef renderer fill:#99FF99,stroke:#333,stroke-width:1px
    classDef external fill:#FF9999,stroke:#333,stroke-width:1px
    classDef service fill:#CCFFCC,stroke:#333,stroke-width:1px
    classDef build fill:#CCCCFF,stroke:#333,stroke-width:1px

    %% Click Events - Main Process
    click MP_Main "https://github.com/electron/fiddle/blob/main/src/main/main.ts"
    click MP_Menu "https://github.com/electron/fiddle/blob/main/src/main/menu.ts"
    click MP_Dialogs "https://github.com/electron/fiddle/blob/main/src/main/dialogs.ts"
    click MP_About "https://github.com/electron/fiddle/blob/main/src/main/about-panel.ts"
    click MP_CLI "https://github.com/electron/fiddle/blob/main/src/main/command-line.ts"
    click MP_FirstRun "https://github.com/electron/fiddle/blob/main/src/main/first-run.ts"
    click MP_Files "https://github.com/electron/fiddle/blob/main/src/main/files.ts"
    click MP_Templates "https://github.com/electron/fiddle/blob/main/src/main/templates.ts"
    click MP_Versions "https://github.com/electron/fiddle/blob/main/src/main/versions.ts"
    click MP_Update "https://github.com/electron/fiddle/blob/main/src/main/update.ts"
    click MP_Squirrel "https://github.com/electron/fiddle/blob/main/src/main/squirrel.ts"
    click MP_NPM "https://github.com/electron/fiddle/blob/main/src/main/npm.ts"
    click MP_SentryMain "https://github.com/electron/fiddle/blob/main/src/main/sentry.ts"
    click MP_IPC "https://github.com/electron/fiddle/blob/main/src/main/ipc.ts"
    click MP_CheckFirstRun "https://github.com/electron/fiddle/blob/main/src/main/utils/check-first-run.ts"
    click MP_Exec "https://github.com/electron/fiddle/blob/main/src/main/utils/exec.ts"
    click MP_GetFiles "https://github.com/electron/fiddle/blob/main/src/main/utils/get-files.ts"
    click MP_ReadFiddle "https://github.com/electron/fiddle/blob/main/src/main/utils/read-fiddle.ts"

    %% Click Events - Preload
    click PB_Preload "https://github.com/electron/fiddle/blob/main/src/preload/preload.ts"
    click PB_IPCEvents "https://github.com/electron/fiddle/blob/main/src/ipc-events.ts"

    %% Click Events - Renderer
    click R_App "https://github.com/electron/fiddle/blob/main/src/renderer/app.tsx"
    click R_Main "https://github.com/electron/fiddle/blob/main/src/renderer/main.tsx"
    click R_State "https://github.com/electron/fiddle/blob/main/src/renderer/state.ts"
    click R_TaskRunner "https://github.com/electron/fiddle/blob/main/src/renderer/task-runner.ts"
    click R_Runner "https://github.com/electron/fiddle/blob/main/src/renderer/runner.ts"
    click R_RemoteLoader "https://github.com/electron/fiddle/blob/main/src/renderer/remote-loader.ts"
    click RC_FileTree "https://github.com/electron/fiddle/blob/main/src/renderer/components/sidebar-file-tree.tsx"
    click RC_PkgManager "https://github.com/electron/fiddle/blob/main/src/renderer/components/sidebar-package-manager.tsx"
    click RC_VersionChooser "https://github.com/electron/fiddle/blob/main/src/renderer/components/commands-version-chooser.tsx"
    click RC_VersionSelect "https://github.com/electron/fiddle/blob/main/src/renderer/components/version-select.tsx"
    click RC_Editor "https://github.com/electron/fiddle/blob/main/src/renderer/components/editor.tsx"
    click RC_EditorsToolbar "https://github.com/electron/fiddle/blob/main/src/renderer/components/editors-toolbar-button.tsx"
    click RC_Output "https://github.com/electron/fiddle/blob/main/src/renderer/components/output.tsx"
    click RC_Settings "https://github.com/electron/fiddle/blob/main/src/renderer/components/settings-general.tsx"
    click RC_Tour "https://github.com/electron/fiddle/blob/main/src/renderer/components/tour.tsx"
    click RC_TourWelcome "https://github.com/electron/fiddle/blob/main/src/renderer/components/tour-welcome.tsx"
    click R_Styling "https://github.com/electron/fiddle/tree/main/src/less"

    %% Click Events - Runner
    click ER "https://github.com/electron/fiddle/blob/main/src/main/utils/exec.ts"

    %% Click Events - Services
    click ES_NPM "https://github.com/electron/fiddle/blob/main/src/main/npm.ts"
    click ES_GitHub "https://github.com/electron/fiddle/blob/main/src/utils/gist.ts"
    click ES_Releases "https://github.com/electron/fiddle/blob/main/tools/fetch-releases.ts"
    click ES_SentryRenderer "https://github.com/electron/fiddle/blob/main/src/renderer/sentry.ts"
    click ES_SentryMain2 "https://github.com/electron/fiddle/blob/main/src/main/sentry.ts"
    click ES_AutoUpdate "https://github.com/electron/fiddle/blob/main/src/main/update.ts"

    %% Click Events - Build
    click BT_WebpackMain "https://github.com/electron/fiddle/blob/main/tools/webpack/webpack.main.config.ts"
    click BT_WebpackRenderer "https://github.com/electron/fiddle/blob/main/tools/webpack/webpack.renderer.config.ts"
    click BT_Forge "https://github.com/electron/fiddle/blob/main/forge.config.ts"
    click BT_CI_Circle "https://github.com/electron/fiddle/blob/main/.circleci/config.yml"
    click BT_CI_GH "https://github.com/electron/fiddle/tree/main/.github/workflows"
```
