Knowledge Base updated: 2026-11-16
Knowledge Base Index
Orientation
This repository is the Electron desktop wrapper for draw.io/diagrams.net. The highest-level flow is the Electron main process launching a desktop window around the embedded draw.io web application, then coordinating local files, exports, printing, updates, and packaging.
Main parts:
src/main/— Electron main-process shell and helper modules.src/test/— unit tests for main-process helper behavior.build/and electron-builder*.json — packaging assets, installer settings, signing, notarization, and platform build helpers..github/workflows/— CI, release, store credential, and packaging automation.drawio/plus.gitmodules/sync.cjs — integration points for the embedded draw.io web app/submodule.
Critical state is local rather than server-side: user diagram files, backup files, watched filesystem paths, update preferences, config paths, and restored window bounds live on the desktop filesystem or Electron app state. There is no database, object store, queue, or service-side cache in this repository.
Architecture diagrams
flowchart TD
subgraph Desktop_App[Electron desktop app]
Main[src/main/electron.js]
Preload[src/main/electron-preload.js and preload.js]
Launch[args url-params config/system paths]
FileState[backup watcher window bounds]
Export[export html pdf png print progress]
Updates[update channel mode disable]
end
subgraph Embedded_App[draw.io web app]
Drawio[drawio submodule / web assets]
Sync[sync.cjs]
end
subgraph Build_Release[Build and release]
Builder[electron-builder*.json]
BuildScripts[build scripts and assets]
CI[.github/workflows]
end
subgraph Verification[Verification]
Tests[src/test]
end
Main --> Launch
Main --> Preload
Main --> FileState
Main --> Export
Main --> Updates
Main --> Drawio
Sync --> Drawio
Builder --> BuildScripts
CI --> Builder
Tests --> Launch
Tests --> FileState
Tests --> Export
Tests --> Updates
flowchart LR
CLI[CLI args / OS open event] --> Args[src/main/args.js]
Args --> Params[src/main/url-params.js]
Config[src/main/config-paths.js] --> Main[src/main/electron.js]
System[src/main/system-path.js] --> Main
Params --> Main
Main --> Window[BrowserWindow]
Preload[src/main/electron-preload.js / preload.js] --> Window
Window --> Drawio[draw.io web UI]
flowchart TD
Request[Export or print request] --> ExportFiles[src/main/export-files.js]
ExportFiles --> Html[src/main/html-export.js]
ExportFiles --> Pdf[src/main/pdf-xml.js]
ExportFiles --> Png[src/main/png-xml.js]
ExportFiles --> Print[src/main/print-options.js]
ExportFiles --> Progress[src/main/progress-bar.js]
Html --> Output[Desktop output file]
Pdf --> Output
Png --> Output
Print --> Output
flowchart LR
CI[GitHub Actions workflows] --> Package[electron-builder configs]
Package --> Assets[build assets/scripts]
Assets --> Win[Windows installers/AppX/MSI]
Assets --> Mac[macOS DMG/notarized app]
Assets --> Linux[Linux/Snap/Flathub artifacts]
CI --> Release[release prep and hashes]
Glossary
- draw.io / diagrams.net — the diagram editor web application embedded by this desktop Electron wrapper.
- Electron Builder — the packaging tool configured by electron-builder*.json and invoked by CI/build scripts.
- AppX/MSI/Snap/Flathub — platform-specific installer or distribution targets represented in build config and workflows.
Codebase-wide invariants
- Main-process production modules are flat JavaScript files under src/…/*.js; representative paths include src/…/electron.js, src/…/export-files.js, and src/…/window-bounds.js.
- Most small helper modules in
src/main/have matching unit tests under src/…/*test.js, for example src/…/args.js with src/…/cli-args.test.js and src/…/window-bounds.js with src/…/window-bounds.test.js; larger shell/UI helpers such as src/…/electron.js and src/…/progress-bar.js are exceptions. - Packaging is split between root Electron Builder configuration files matching electron-builder*.json and helper/assets under
build/**. - CI and release automation lives under .github/…/*.yml, with release operator documentation under doc/RELEASE_PROCESS.md and personal-build documentation under doc/BUILDING_FOR_PERSONAL_USE.md.
Routing table
-
changes to BrowserWindow lifecycle, app menus, IPC, preload/security boundaries, or desktop app startup orchestration -> docs/electron-shell.md
-
src/…/url-params.js -> docs/launch-configuration-and-inputs.md
-
src/…/config-paths.js -> docs/launch-configuration-and-inputs.md
-
src/…/system-path.js -> docs/launch-configuration-and-inputs.md
-
src/…/cli-args.test.js -> docs/launch-configuration-and-inputs.md
-
src/…/url-params.test.js -> docs/launch-configuration-and-inputs.md
-
src/…/config-paths.test.js -> docs/launch-configuration-and-inputs.md
-
src/…/system-path.test.js -> docs/launch-configuration-and-inputs.md
-
changes to command-line parsing, URL parameters, app path resolution, or launch-time configuration -> docs/launch-configuration-and-inputs.md
-
src/…/export-files.test.js -> docs/export-and-print-pipeline.md
-
src/…/html-export.test.js -> docs/export-and-print-pipeline.md
-
src/…/print-options.test.js -> docs/export-and-print-pipeline.md
-
any change to export formats, print option parsing, generated files, or export progress UI -> docs/export-and-print-pipeline.md
-
src/…/backup-file.js -> docs/file-state-backups-and-watchers.md
-
src/…/file-watcher.js -> docs/file-state-backups-and-watchers.md
-
src/…/window-bounds.js -> docs/file-state-backups-and-watchers.md
-
src/…/backup-file.test.js -> docs/file-state-backups-and-watchers.md
-
src/…/file-watcher.test.js -> docs/file-state-backups-and-watchers.md
-
src/…/window-bounds.test.js -> docs/file-state-backups-and-watchers.md
-
changes to backup naming/cleanup, filesystem watching, file-change detection, or restored window geometry -> docs/file-state-backups-and-watchers.md
-
changes to update channels, update modes, disabled update behavior, or updater preference handling -> docs/update-preferences.md
-
build/**-> docs/packaging-and-installers.md -
.nvmrc-> docs/packaging-and-installers.md -
changes to installer targets, signing, notarization, icons/assets, or package/build scripts -> docs/packaging-and-installers.md
-
.github/workflows/**-> docs/ci-release-workflows.md -
.github/ISSUE_TEMPLATE/**-> docs/ci-release-workflows.md -
doc/BUILDING_FOR_PERSONAL_USE.md -> docs/ci-release-workflows.md
-
changes to CI jobs, release preparation, store credential checks, hash generation, Flathub releases, or issue automation -> docs/ci-release-workflows.md
-
src/test/**-> docs/unit-test-suite.md -
changes to test harness, unit-test commands, or helper test coverage strategy -> docs/unit-test-suite.md
-
drawio/**-> docs/drawio-webapp-integration.md -
.gitmodules-> docs/drawio-webapp-integration.md -
changes to the embedded draw.io app/submodule, sync process, repository dependency setup, or developer onboarding around draw.io integration -> docs/drawio-webapp-integration.md