# zalo/cascadestudio architecture

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

- Interactive diagram: https://gitdiagram.com/zalo/cascadestudio
- Repository: https://github.com/zalo/cascadestudio

## Overview

1. **Overall shape**
   - This is an npm workspaces monorepo with two runtime packages: `cascade-core` and `cascade-studio`.
   - `cascade-core` is the reusable CAD engine; `cascade-studio` is the browser-based IDE built on top of it.
   - The architectural boundary is clear: core contains modeling/runtime logic, studio contains UI, layout, and user interaction.

2. **`cascade-core`: modeling engine boundary**
   - `packages/cascade-core/src/index.js` exposes the package API.
   - `CascadeEngine.js` is the main-thread façade that clients use to initialize the engine and submit code.
   - It talks to a Web Worker through `MessageBus.js`, which is the main isolation boundary between UI code and CAD execution.

3. **Worker-based execution model**
   - `packages/cascade-core/src/worker/CascadeWorker.js` is the worker entry point.
   - User-authored model code is evaluated inside the worker, not on the main thread.
   - This keeps heavy geometry operations and kernel interaction off the UI thread and makes the engine embeddable in other web apps.

4. **CAD standard library and geometry operations**
   - `StandardLibrary.js` provides the modeling API exposed to users: primitives, sketches, transforms, booleans, fillets, selectors, measurements, and similar operations.
   - The README’s `Box`, `Sketch`, `Union`, `FilletEdges`, `Edges`, `Volume`, etc. all come from this layer.
   - This library is the semantic layer that user scripts target before any rendering or export happens.

5. **OpenCascade kernel integration**
   - The repo’s CAD backend is OpenCascade via `opencascade.js`/OCCT, which is a major architectural dependency.
   - `ShapeToMesh.js` converts kernel shapes into renderable mesh data.
   - `FileUtils.js` handles CAD file import/export paths such as STEP, IGES, STL, and related shape I/O.

6. **OpenSCAD support as a separate input language**
   - `packages/cascade-core/src/openscad/OpenSCADTranspiler.js` converts OpenSCAD into the JavaScript standard-library form used by the engine.
   - This means OpenSCAD is not a parallel execution engine; it is a source-language front end feeding the same core modeling pipeline.
   - In the studio, `packages/cascade-studio/src/openscad/OpenSCADMonaco.js` provides the editor-side language integration.

7. **`cascade-studio`: browser application shell**
   - `packages/cascade-studio/src/main.js` is the entry point for the IDE.
   - `CascadeMain.js` coordinates the application shell and layout.
   - The app is structured as a browser SPA with static assets, PWA support, and deployment to GitHub Pages/Vercel.

8. **Studio UI subsystem boundaries**
   - `CascadeView.js` owns the 3D viewport and modeling timeline.
   - `EditorManager.js` owns the Monaco editor and code evaluation flow.
   - `ConsoleManager.js` captures logs/errors, and `GUIManager.js` manages Tweakpane-based parameter controls.
   - These modules are separate UI concerns; they do not own CAD logic themselves.

9. **Studio-to-core integration**
   - `CascadeAPI.js` exposes `window.CascadeAPI` for automation and external control, including Playwright-driven tests.
   - The studio uses the core engine as a service boundary: editor input is compiled/evaluated by the engine, and results come back as mesh/history/log data.
   - The viewport then renders mesh output, while the console and GUI reflect evaluation state and parameters.

10. **Data flow from code to model**
   - User edits JavaScript or OpenSCAD in Monaco.
   - The source is passed into the engine worker through the `CascadeEngine`/`MessageBus` path.
   - The worker evaluates the code using the standard library, builds OCCT shapes, optionally applies imports/transforms/booleans, and then triangulates to mesh data.
   - Studio receives the result for rendering, history scrubbing, exporting, and URL serialization/sharing.

11. **Import/export and persistence**
   - File import/export is a cross-cutting capability in `cascade-core`, not a studio-only feature.
   - The README indicates support for `.STEP`, `.IGES`, `.STL` import and `.STEP`, `.STL`, `.OBJ` export.
   - Project state is also serialized into the URL, which is a key persistence/share boundary in the system.

12. **Build and distribution**
   - The repo is built with esbuild, with `cascade-core` built before `cascade-studio`.
   - `packages/cascade-core/scripts/build.cjs` and `packages/cascade-studio/scripts/build.cjs` produce the distributed artifacts.
   - The studio output is served from `packages/cascade-studio/dist`, with PWA/service-worker support for offline use.

13. **Testing and automation**
   - The root `test/` directory contains Playwright-based end-to-end tests.
   - Tests cover geometry operations, OpenSCAD support, exports, and screenshot regression.
   - The browser automation surface is important architecturally because `CascadeAPI` is designed to support it.

14. **Key diagram boundaries to draw**
   - One boundary around the **browser UI layer** (`cascade-studio`).
   - One boundary around the **engine layer** (`cascade-core`), split into main-thread API and worker execution.
   - One boundary around the **OpenCascade kernel/WASM-backed geometry runtime** inside the worker.
   - One boundary around **static assets and deployment** (icons, fonts, service worker, GitHub Pages/Vercel), which support distribution but do not change modeling logic.

Main entry points: [`packages/cascade-studio/src/CascadeMain.js`](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/CascadeMain.js) (Shell), [`packages/cascade-core/src/worker/CascadeWorker.js`](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/worker/CascadeWorker.js) (Worker), [`packages/cascade-core/src/engine/CascadeEngine.js`](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/engine/CascadeEngine.js) (Engine), [`packages/cascade-studio/src/EditorManager.js`](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/EditorManager.js) (Editor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
  node_monorepo(("Workspaces<br/>npm monorepo"))
end

subgraph group_core["cascade-core"]
  node_core_index["API<br/>package entry<br/>[index.js]"]
  node_engine["Engine<br/>main-thread façade<br/>[CascadeEngine.js]"]
  node_bus["Message Bus<br/>worker bridge<br/>[MessageBus.js]"]
  node_worker["Worker<br/>execution runtime<br/>[CascadeWorker.js]"]
  node_stdlib["Stdlib<br/>modeling API<br/>[StandardLibrary.js]"]
  node_kernel[("OpenCascade<br/>CAD kernel")]
  node_mesh["Mesh<br/>triangulation<br/>[ShapeToMesh.js]"]
  node_files["CAD I/O<br/>import/export<br/>[FileUtils.js]"]
  node_scad_frontend["OpenSCAD<br/>source frontend"]
end

subgraph group_studio["cascade-studio"]
  node_studio_main["Main<br/>app entry<br/>[main.js]"]
  node_studio_shell["Shell<br/>app coordinator<br/>[CascadeMain.js]"]
  node_viewport["Viewport<br/>3D view<br/>[CascadeView.js]"]
  node_editor["Editor<br/>[EditorManager.js]"]
  node_console["Console<br/>log panel<br/>[ConsoleManager.js]"]
  node_gui["GUI<br/>parameters panel<br/>[GUIManager.js]"]
  node_api["CascadeAPI<br/>automation API<br/>[CascadeAPI.js]"]
  node_scad_editor["SCAD Monaco<br/>language integration<br/>[OpenSCADMonaco.js]"]
end

subgraph group_delivery["Delivery"]
  node_pwa["PWA + Deploy<br/>distribution<br/>[service-worker.js]"]
end

subgraph group_testing["Testing"]
  node_tests["Playwright<br/>e2e suite"]
end

node_monorepo -->|"contains"| node_core_index
node_monorepo -->|"contains"| node_studio_main
node_core_index -->|"exports"| node_engine
node_engine -->|"dispatches"| node_bus
node_bus -->|"isolates"| node_worker
node_worker -->|"evaluates"| node_stdlib
node_stdlib -->|"drives"| node_kernel
node_worker -->|"triangulates"| node_mesh
node_worker -->|"imports/exports"| node_files
node_scad_frontend -->|"transpiles to"| node_stdlib
node_studio_main -->|"boots"| node_studio_shell
node_studio_shell -->|"coordinates"| node_viewport
node_studio_shell -->|"coordinates"| node_editor
node_studio_shell -->|"coordinates"| node_console
node_studio_shell -->|"coordinates"| node_gui
node_editor -->|"runs code"| node_engine
node_engine -->|"returns model"| node_viewport
node_api -->|"drives"| node_tests
node_scad_editor -->|"extends"| node_editor
node_pwa -->|"packages"| node_studio_main
node_editor -->|"exposes"| node_api

click node_core_index "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/index.js"
click node_engine "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/engine/CascadeEngine.js"
click node_bus "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/engine/MessageBus.js"
click node_worker "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/worker/CascadeWorker.js"
click node_stdlib "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/worker/StandardLibrary.js"
click node_mesh "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/worker/ShapeToMesh.js"
click node_files "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/worker/FileUtils.js"
click node_scad_frontend "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/openscad/OpenSCADTranspiler.js"
click node_studio_main "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/main.js"
click node_studio_shell "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/CascadeMain.js"
click node_viewport "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/CascadeView.js"
click node_editor "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/EditorManager.js"
click node_console "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/ConsoleManager.js"
click node_gui "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/GUIManager.js"
click node_api "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/CascadeAPI.js"
click node_scad_editor "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/openscad/OpenSCADMonaco.js"
click node_pwa "https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/service-worker.js"
click node_tests "https://github.com/zalo/cascadestudio/blob/master/test/cascade-studio.spec.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_monorepo toneBlue
class node_core_index,node_engine,node_bus,node_worker,node_stdlib,node_kernel,node_mesh,node_files,node_scad_frontend toneAmber
class node_studio_main,node_studio_shell,node_viewport,node_editor,node_console,node_gui,node_api,node_scad_editor toneMint
class node_pwa toneRose
class node_tests toneIndigo
```

## Components

### Workspace

npm workspaces monorepo

- **Workspaces**: npm monorepo · Root workspace coordinating core and studio packages

### cascade-core

Reusable CAD engine

- [API](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/index.js): package entry · Public entry point for cascade-core · `packages/cascade-core/src/index.js`
- [Engine](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/engine/CascadeEngine.js): main-thread façade · Initializes the engine and submits model code · `packages/cascade-core/src/engine/CascadeEngine.js`
- [Message Bus](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/engine/MessageBus.js): worker bridge · Isolation boundary between UI code and CAD execution · `packages/cascade-core/src/engine/MessageBus.js`
- [Worker](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/worker/CascadeWorker.js): execution runtime · Worker entry point that evaluates user-authored model code · `packages/cascade-core/src/worker/CascadeWorker.js`
- [Stdlib](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/worker/StandardLibrary.js): modeling API · User-facing CAD primitives, transforms, booleans, selectors, and measurements · `packages/cascade-core/src/worker/StandardLibrary.js`
- **OpenCascade**: CAD kernel · WASM-backed geometry kernel used for modeling and shape operations
- [Mesh](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/worker/ShapeToMesh.js): triangulation · Converts kernel shapes into renderable mesh data · `packages/cascade-core/src/worker/ShapeToMesh.js`
- [CAD I/O](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/worker/FileUtils.js): import/export · STEP, IGES, STL, OBJ and related shape file handling · `packages/cascade-core/src/worker/FileUtils.js`
- [OpenSCAD](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-core/src/openscad/OpenSCADTranspiler.js): source frontend · Transpiles OpenSCAD into the shared JavaScript modeling pipeline · `packages/cascade-core/src/openscad/OpenSCADTranspiler.js`

### cascade-studio

Browser IDE built on core

- [Main](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/main.js): app entry · Browser IDE entry point · `packages/cascade-studio/src/main.js`
- [Shell](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/CascadeMain.js): app coordinator · Coordinates the studio application shell and layout · `packages/cascade-studio/src/CascadeMain.js`
- [Viewport](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/CascadeView.js): 3D view · Owns the model view and timeline rendering · `packages/cascade-studio/src/CascadeView.js`
- [Editor](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/EditorManager.js): code editor · Monaco editor and code evaluation flow · `packages/cascade-studio/src/EditorManager.js`
- [Console](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/ConsoleManager.js): log panel · Captures logs, errors, and evaluation feedback · `packages/cascade-studio/src/ConsoleManager.js`
- [GUI](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/GUIManager.js): parameters panel · Tweakpane-based parameter controls · `packages/cascade-studio/src/GUIManager.js`
- [CascadeAPI](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/CascadeAPI.js): automation API · Window-level control surface for automation and external scripting · `packages/cascade-studio/src/CascadeAPI.js`
- [SCAD Monaco](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/src/openscad/OpenSCADMonaco.js): language integration · OpenSCAD editor support in the studio · `packages/cascade-studio/src/openscad/OpenSCADMonaco.js`

### Delivery

Build, PWA, and deployment boundary

- [PWA + Deploy](https://github.com/zalo/cascadestudio/blob/master/packages/cascade-studio/service-worker.js): distribution · Static assets, service worker, and deployment packaging · `packages/cascade-studio/service-worker.js`

### Testing

Automation and regression coverage

- [Playwright](https://github.com/zalo/cascadestudio/blob/master/test/cascade-studio.spec.js): e2e suite · Browser automation and regression tests · `test/cascade-studio.spec.js`

## Connections

- Workspaces → API: contains · Workspace includes the reusable engine package
- Workspaces → Main: contains · Workspace includes the browser IDE package
- API → Engine: exports · Package entry exposes the engine API
- Engine → Message Bus: dispatches · Main thread communicates through the message bus
- Message Bus → Worker: isolates · Worker boundary runs model execution off the UI thread
- Worker → Stdlib: evaluates · Worker executes user code against the modeling API
- Stdlib → OpenCascade: drives · Standard library builds geometry through OpenCascade
- Worker → Mesh: triangulates · Shapes are converted into renderable mesh data
- Worker → CAD I/O: imports/exports · Worker handles CAD file I/O paths
- OpenSCAD → Stdlib: transpiles to · OpenSCAD is lowered into the shared modeling API
- Main → Shell: boots · Application entry initializes the studio shell
- Shell → Viewport: coordinates · Shell manages the 3D viewport
- Shell → Editor: coordinates · Shell manages source editing
- Shell → Console: coordinates · Shell manages logging and errors
- Shell → GUI: coordinates · Shell manages parameter controls
- Editor → Engine: runs code · Editor submits JS/OpenSCAD source to the engine
- Engine → Viewport: returns model · Engine results feed the viewport as meshes/history
- CascadeAPI → Playwright: drives · Automation surface supports Playwright-based testing
- SCAD Monaco → Editor: extends · OpenSCAD editor support plugs into the code editor
- PWA + Deploy → Main: packages · Static app shell is bundled for distribution and offline use
- Editor → CascadeAPI: exposes · Studio state can be controlled externally through the API
