OpenCandle is an Electron desktop app with a React and TypeScript renderer. This page is a short map of how the parts fit together.
+--------------------------- Electron main process (electron/) ---------------------------+
| windows, tray, menus workspace storage (atomic JSON) native file dialogs |
| data providers: Alpaca, Coinbase, FRED, SEC key store (safeStorage) bar caches |
| script runtime: QuickJS workers alert notifications and webhooks |
+-------------------------------------+---------------------------------------------------+
| fixed, validated IPC calls (electron/preload.cjs)
+-------------------------------------v---------------------------------------------------+
| Renderer (src/), sandboxed, no Node access, served from the private lv://app scheme |
| ui/ (React) -> domain/ (indicators, strategies, alerts, replay, paper trading) |
| -> chart/ (Vela chart engine, chart types, drawings, layouts) |
+-----------------------------------------------------------------------------------------+
src/ui/holds the React interface: the main window, dialogs, panels, menus, themes and icons.src/domain/is the logic that does not depend on the screen: indicator and pattern calculations, built-in strategies, the strategy tester engine, alerts, replay, paper trading, intervals and sessions, data imports and the Pine importer.src/chart/connects the domain to the Vela chart engine: chart types (including derived types such as Renko, Kagi and footprint), price and time scales, drawing tools and their painters, multi-chart layouts and image export.- Feature folders:
analysis-news/,fundamentals/,market-views/,portfolio/,strategy-report/,watchlists/,vwap/.
The renderer runs with context isolation, Chromium sandboxing, Node integration disabled and web security on. Its content security policy only allows packaged scripts and blocks remote connections, so the renderer never talks to the internet directly.
main.cjscreates windows, registers thelv://appscheme, takes a single-instance lock on the profile, and handles IPC. Every privileged call checks that it came from a trusted window.preload.cjsexposes a small typed bridge (window.lv, seebridge.d.ts). No file path, URL, shell command or credential crosses it from the renderer.storage.cjssaves the workspace as bounded JSON in the profile folder: each save writes a temporary file, flushes it to disk and renames it into place, with revision checks so two saves cannot overwrite each other.public-alpaca.cjs,public-coinbase.cjs,public-fred.cjsandpublic-sec.cjsare the data providers. They load only when first used, call fixed endpoints, cap response sizes, rate-limit and back off.bar-cache.cjscaches downloaded bars in the profile folder.import-data.cjsopens native file pickers for imports, with size limits and strict UTF-8 decoding.script-runtime.cjs,script-worker.cjsand related files run CandleScript.alert-notify.cjsandalert-webhook.cjsdeliver alerts.
CandleScript runs in a QuickJS WebAssembly runtime inside a dedicated worker, one fresh runtime per job. The guest has no file, network, process or credential objects, and limits apply to source size, heap, stack, compute time, worker lifetime and output size. Results include plots, visuals, drawing objects, alerts, virtual orders and a resumable state snapshot. See candlescript.md.
The Pine importer (src/domain/pine-import/) is a translator only: it parses Pine source and writes CandleScript. It never runs Pine. See pine-import.md.
- The renderer asks for bars by symbol and interval.
- Built-in practice data is generated in the renderer. Live and historical market data comes through the main-process providers, which validate the request and return validated bars.
- Indicators, patterns, scripts and strategies calculate on the bars the chart has. In replay, they see only the bars up to the replay point.
- Drawings, layouts, alerts, scripts and settings are part of the workspace and saved through
storage.cjs.
Charts are drawn by Vela. OpenCandle applies a small, documented patch to the installed Vela package (src/chart/apply-vela-compat-patch.mjs, run on npm ci and verified before dev, build and test) and a few build-time transforms in vite.config.ts. Every modified file carries a notice. Details: vela-modification.md.
npm run package builds the renderer and stages dist/, electron/, minimal package metadata, licence notices and only the QuickJS runtime modules the app needs into a portable Windows folder and ZIP. Packaged builds enable Electron security fuses. See building-and-packaging.md.