Blockwork is two processes on the desktop: the daemon, which owns every macro, hotkey, watcher and run, and the editor, a Qt Quick window that only draws what the daemon tells it. Closing the window leaves the daemon in the tray, so hotkeys and schedules keep working.
The editor starts the daemon if none is running: the blockwork-daemon
binary beside it, or blockwork --daemon inside an AppImage, which has one
executable (blockwork-qt/src/daemon_client.rs).
blockwork (Qt) blockwork-daemon
┌──────────────────────┐ socket ┌───────────────────────────────┐
│ QML ── invoke() ──► │ ──────────► │ server.rs ─► Backend::dispatch│
│ app_bridge.rs │ NDJSON │ commands/*.rs │
│ daemon_client.rs │ ◄────────── │ AppHandle ◄─ emit_state │
│ appState ◄ stateJson │ State │ watchers, runner threads │
└──────────────────────┘ └───────────────────────────────┘
Take dragging a block onto the canvas.
- QML. The canvas (from blockstitch) asks the host to add an
instruction.
Main.qml'sinvoke(command, args)hands the name and a JSON object tobridge.invokeCommand(blockwork-qt/src/app_bridge.rs). - Editor glue.
app_bridge.rsqueues aRequest::Invokefordaemon_client.rs, which writes aClientMessageline to the daemon's socket (blockwork-protocol: one JSON message per line, a Unix socket or a named pipe on Windows). - Daemon.
blockwork-daemon/src/server.rsreads the line and callsBackend::dispatch(command, args). - Dispatch.
blockwork-app/src/dispatch.rsreads the camelCase arguments and calls the matching function underblockwork-app/src/commands/(editing.rs,strands.rs,blocks.rs, ...). Edits that only touch the block graph go through blockstitch'sEditCommands; rules that are Blockwork's own live onMacro(blockwork-model/src/macros/document_rules.rs). - Save and publish. A command that changes a macro pushes an undo step,
saves it (
blockwork-core/src/config/persistence.rs), and callsemit_state_updated(blockwork-app/src/state.rs). That builds aStateDto, serializes it once, and sendsEvent::Stateon theAppHandle's broadcast channel. - Back to the editor. The server forwards the state to the connected
window.
daemon_client.rsturns it intoEvent::State,app_bridge.rssetsstateJson, andMain.qmlparses it intoappState, which every page binds to.
A command's return value (an id, a fragment) comes back the same way as a reply tagged with the request's key, for the callers that wait on one.
commands/running.rs starts a run with Run::run (blockwork-core/src/macros/runner.rs)
on its own thread (macros_thread.rs). The runner walks the strands, sends
input through the platform's InputBackend (macros/backend/), and marks
which blocks are running in macros/trace.rs. A trace-watch thread in
Backend::start sends that as Event::Trace, which the editor draws as the
run highlight.
Trigger blocks (When...) are started by watchers in blockwork-app, one
file each (watch/key.rs, watch/time.rs, watch/window.rs, ...). Each
watcher is started from Backend::start in blockwork-app/src/lib.rs, looks
for its InstructionKind in every macro, and starts the strand when its
condition happens.
blockwork-web is the same editor without the daemon, built on
blockwork-model alone, for the home page demo on blockworked.com. The page runs Blockwork's own EditorPage.qml, built with
Qt for WebAssembly (blockworked.com/qt-demo). In place of the daemon,
blockworked.com's qt-demo/DemoBackend.qml sends each command to a Core object that links
blockwork-web as a static library and calls it through blockstitch's C ABI
(blockstitch_ffi::export_abi!). Demo::dispatch (session.rs) keeps one
in-memory session and answers with the new state. Nothing is saved and
nothing runs.
The canvas commands (strands, blocks, values, comments, variables, lists,
custom blocks, undo) are written once, in blockwork-model/src/editing.rs.
Each host hands over its document through editing::Document: the app's
AppDoc (commands/editing.rs) saves and keeps its live variable and list
stores in step, and the page's Demo only tidies signal names on a change. What only one side has
stays there: the app's library, runs and settings, and the page's in-memory
macro list. blockwork-app/src/web_parity.rs replays one script through both
and fails if their documents differ, and another test fails when a web
command is missing from that script.
blockwork-ffi is a C ABI over the same core for running inside another
process (the Geometry Dash mod). It has no daemon or editor; see its
README.
Each repo builds against a fixed commit of the one it depends on. Move a pin after the upstream change lands on its main branch.
| Pin | Where | Who moves it, and how |
|---|---|---|
| blockstitch commit | Cargo.toml ([workspace.dependencies]), packaging/flatpak/ |
this repo: node scripts/set-blockstitch-rev.js <sha>, then cargo update -p blockstitch-core -p blockstitch-qml -p blockstitch-ffi |
| Blockwork commit for the website's editor | blockworked.com qt-demo/sources.env (BLOCKWORK_REV) |
the website; blockstitch and lucide-qt follow from that commit's Cargo.lock |
| Qt for WebAssembly and Emscripten | blockworked.com qt-demo/sources.env |
the website; desktop CI uses QT_VERSION in .github/workflows/ |
| Blockwork commit for the community site | Blockwork-community-blocks .blockwork-rev |
the community site; node scripts/sync-capabilities.js copies capabilities.json |
| Browser bridge protocol | PROTOCOL in blockwork-core/src/browser.rs, PROTOCOL.md in blockwork-browser |
bump both together when a message changes |
| Minimum Rust | rust-version in Cargo.toml (and blockstitch's) |
CI builds the workspace with it |
| C header for the Geometry Dash mod | blockwork-ffi/include/, built into blockwork-gd |
regenerated by blockwork-ffi's build; CI fails on a stale copy |