# kalo08/esp32-wasm-toolchain architecture

> Architecture diagram of the GitHub repository kalo08/esp32-wasm-toolchain, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kalo08/esp32-wasm-toolchain
- Repository: https://github.com/kalo08/esp32-wasm-toolchain
- Video tour (about a minute): https://gitdiagram.com/kalo08/esp32-wasm-toolchain/video

## Overview

This browser-based ESP32-S3 toolchain turns Arduino C++ into flash images using WebAssembly GCC/binutils, then writes them over Web Serial. The main flow is sketch preparation, worker orchestration of compile/assemble/link, image generation, and flashing. Optional library detection and pack loading extend compilation and linking. Toolchain binaries and manifests are fetched as static assets; their implementation is not present in the source tree, so those assets are shown as an external dependency. The detailed stage flow is grounded in the worker and README; unsampled pack contents are not expanded.

Main entry points: [`src/cppworker.js`](https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppworker.js) (Build worker), [`src/cppbuild.js`](https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppbuild.js) (Build API), [`src/ino.js`](https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/ino.js) (INO conversion), [`src/cppfeatures.js`](https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppfeatures.js) (Feature detection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Sketch input"]
  node_ino["INO conversion<br/>[ino.js]"]
  node_build_api["Build API<br/>[cppbuild.js]"]
end

subgraph group_build["Browser build"]
  node_worker["Build worker<br/>[cppworker.js]"]
  node_compiler["C++ compiler<br/>[cppworker.js]"]
  node_assembler["Assembler<br/>[cppworker.js]"]
  node_linker["SDK linker<br/>[cppworker.js]"]
  node_toolchain_assets["Toolchain assets"]
end

subgraph group_libraries["Library support"]
  node_feature_detection["Feature detection<br/>[cppfeatures.js]"]
  node_library_packs["Optional library packs<br/>[cppworker.js]"]
  node_supported_libraries["Arduino and ESP32 libraries"]
end

subgraph group_flash["Image and flashing"]
  node_image_builder["ELF image builder<br/>[elf2image.js]"]
  node_flash_api["Flash API<br/>[flash.js]"]
  node_esptool["esptool-js<br/>[flash.js]"]
end

node_author(("Sketch author"))
node_board(("ESP32-S3 board"))

node_author -->|"prepares sketch"| node_ino
node_author -->|"submits C++"| node_build_api
node_ino -->|"returns C++"| node_build_api
node_build_api -->|"starts worker"| node_worker
node_worker -->|"detects features"| node_feature_detection
node_worker -->|"fetches manifests and binaries"| node_toolchain_assets
node_worker -->|"runs compile"| node_compiler
node_worker -->|"runs assemble"| node_assembler
node_worker -->|"runs link"| node_linker
node_feature_detection -->|"selects packs"| node_library_packs
node_worker -->|"loads headers and objects"| node_library_packs
node_supported_libraries -.->|"provided as packs"| node_library_packs
node_worker -->|"converts ELF"| node_image_builder
node_author -->|"requests flashing"| node_flash_api
node_flash_api -->|"writes flash images"| node_esptool
node_esptool -->|"flashes over Web Serial"| node_board

click node_ino "https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/ino.js"
click node_build_api "https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppbuild.js"
click node_worker "https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppworker.js"
click node_compiler "https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppworker.js"
click node_assembler "https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppworker.js"
click node_linker "https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppworker.js"
click node_feature_detection "https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppfeatures.js"
click node_library_packs "https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppworker.js"
click node_image_builder "https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/elf2image.js"
click node_flash_api "https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/flash.js"
click node_esptool "https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/flash.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ino,node_build_api toneBlue
class node_worker,node_compiler,node_assembler,node_linker,node_toolchain_assets toneAmber
class node_feature_detection,node_library_packs,node_supported_libraries toneMint
class node_image_builder,node_flash_api,node_esptool toneRose
class node_author,node_board toneIndigo
```

## Components

### Sketch input

- [INO conversion](https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/ino.js): `src/ino.js`
- [Build API](https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppbuild.js): `src/cppbuild.js`

### Browser build

- [Build worker](https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppworker.js): `src/cppworker.js`
- [C++ compiler](https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppworker.js): `src/cppworker.js`
- [Assembler](https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppworker.js): `src/cppworker.js`
- [SDK linker](https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppworker.js): `src/cppworker.js`
- **Toolchain assets**

### Library support

- [Feature detection](https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppfeatures.js): `src/cppfeatures.js`
- [Optional library packs](https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/cppworker.js): `src/cppworker.js`
- **Arduino and ESP32 libraries**

### Image and flashing

- [ELF image builder](https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/elf2image.js): `src/elf2image.js`
- [Flash API](https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/flash.js): `src/flash.js`
- [esptool-js](https://github.com/kalo08/esp32-wasm-toolchain/blob/main/src/flash.js): `src/flash.js`

### Other components

- **Sketch author**
- **ESP32-S3 board**

## Connections

- Sketch author → INO conversion: prepares sketch (evidence: `README.md`)
- Sketch author → Build API: submits C++ (evidence: `README.md`)
- INO conversion → Build API: returns C++ (evidence: `src/ino.js`)
- Build API → Build worker: starts worker (evidence: `src/cppbuild.js`)
- Build worker → Feature detection: detects features (evidence: `src/cppworker.js`)
- Build worker → Toolchain assets: fetches manifests and binaries (evidence: `src/cppworker.js`)
- Build worker → C++ compiler: runs compile (evidence: `src/cppworker.js`)
- Build worker → Assembler: runs assemble (evidence: `src/cppworker.js`)
- Build worker → SDK linker: runs link (evidence: `src/cppworker.js`)
- Feature detection → Optional library packs: selects packs (evidence: `src/cppworker.js`)
- Build worker → Optional library packs: loads headers and objects (evidence: `src/cppworker.js`)
- Arduino and ESP32 libraries → Optional library packs: provided as packs (evidence: `README.md`)
- Build worker → ELF image builder: converts ELF (evidence: `src/cppworker.js`)
- Sketch author → Flash API: requests flashing (evidence: `README.md`)
- Flash API → esptool-js: writes flash images (evidence: `src/flash.js`)
- esptool-js → ESP32-S3 board: flashes over Web Serial (evidence: `README.md`)
