This document provides a high-level introduction to the OpenCOR webapp codebase, including its purpose, architecture, and key technologies. It serves as an entry point for understanding the system before diving into specific subsystems.
For detailed information about specific aspects of the system, see:
OpenCOR is a web-based modeling environment for organizing, editing, simulating, and analyzing CellML files. The codebase implements a dual-deployment application that can run either as a cross-platform Electron desktop application or as a standalone web application accessible through modern browsers.
Sources: README.md1-11 src/renderer/README.md1-16
OpenCOR exists in two deployable forms that share the same Vue.js renderer codebase:
| Variant | Platform Support | Backend | Distribution |
|---|---|---|---|
| Desktop Application | Windows, Linux, macOS (Intel + ARM) | Native C++ via Node.js addon | GitHub Releases (installers) |
| Web Application | Any modern browser | WebAssembly | opencor.ws (static files), npm package |
The desktop version provides native performance and OS integration (file dialogs, native menus, auto-updates), while the web version offers universal accessibility without installation requirements. Both variants can also function as embeddable Vue components via the @opencor/opencor npm package.
Sources: README.md5-8 src/renderer/README.md5-9 package.json18-26 src/renderer/package.json26-28
Technology Decisions:
Sources: package.json46-92 src/renderer/package.json55-90 src/renderer/README.md11-15 BUILD.md1-7
The following diagram maps the conceptual architecture to actual code entities:
Key Components:
OpenCOR.vue: Central orchestrator managing UI state, file operations, and simulation modeContentsComponent.vue: Implements tabbed interface for multiple open filesSimulationExperimentView.vue: Handles CellML/SED-ML simulation execution and visualizationlocApi.ts: Unified API abstracting native vs WebAssembly backend selectionelectronApi.ts: IPC bridge exposing main process services to rendererSources: package.json17 src/renderer/package.json26 High-level diagrams (Diagram 1, 5, 6)
Development Scripts:
| Command | Description | Output |
|---|---|---|
bun install | Install all npm dependencies | node_modules/ |
bun libopencor | Build native C++ module using cmake-js | dist/libOpenCOR/libOpenCOR.node |
bun dev | Start Electron app with hot reload | Running Electron process |
bun dev:web | Start web app dev server | http://localhost:5173 |
bun build | Build production bundles | out/main/, out/renderer/ |
bun build:web | Build web app for deployment | src/renderer/dist/ |
bun release | Package installers for current platform | dist/OpenCOR-* installers |
Sources: package.json27-44 BUILD.md34-83 src/renderer/BUILD.md34-46 High-level diagram 3
OpenCOR uses a semantic versioning scheme with automated date-based minor versions:
Format: MAJOR.YYYYMMDD.PATCH
0)20260129)Example: 0.20260129.1 indicates major version 0, released on January 29, 2026, patch 1 of that day.
The version is synchronized across both package.json files using the bun version:new script.
Sources: package.json26 src/renderer/package.json42 src/renderer/scripts/version.js1-50
OpenCOR processes three primary file formats related to computational biology modeling:
| Format | Purpose | File Extension | Processing |
|---|---|---|---|
| CellML | Mathematical models of biological systems | .cellml | Parsed by libOpenCOR, can be wrapped in default SED-ML |
| SED-ML | Simulation Experiment Description | .sedml | Defines simulation parameters, model changes, solver config |
| OMEX/COMBINE | Archive format bundling models and experiments | .omex | Unpacked to extract CellML and SED-ML files |
All file processing is handled through the locApi abstraction, which delegates to either the native C++ libOpenCOR.node module (desktop) or the WebAssembly module (web).
Sources: README.md3 src/renderer/README.md3 High-level diagram 4
The codebase uses conditional compilation and runtime detection to adapt behavior across deployment targets:
Runtime Detection Code Entities:
window.electronApi: Injected by preload script, indicates Electron environmentisPackaged(): Function in src/renderer/src/common/electron.ts3-5isWindows(), isLinux(), isMacOs(): Platform detection utilities src/renderer/src/common/electron.ts7-17Sources: src/renderer/src/common/electron.ts1-18 src/renderer/src/types/types.d.ts1-18 High-level diagram 6
| Path | Purpose |
|---|---|
src/main/ | Electron main process (Node.js context) |
src/preload/ | Electron preload scripts (security bridge) |
src/renderer/ | Frontend application (Vue.js components) |
src/renderer/src/components/ | Vue components for UI |
src/renderer/src/libopencor/ | libOpenCOR API wrapper and WebAssembly module |
dist/ | Build outputs (installers, archives) |
out/ | Compiled Electron application bundles |
For detailed directory structure analysis, see Project Structure.
Sources: src/renderer/scripts/clean.js3-15 BUILD.md1-94
OpenCOR can be embedded in other Vue 3 applications as an npm package:
Installation:
Basic Usage (Full Application):
Embedded Simulation Mode:
Props:
| Prop | Type | Default | Description |
|---|---|---|---|
omex | string | null | null | URL of OMEX file; if provided, opens directly in simulation mode |
theme | 'light' | 'dark' | 'system' | 'system' | UI theme (set once at initialization, non-reactive) |
Sources: src/renderer/README.md17-68 src/renderer/package.json35-41
This overview provides the foundation for understanding the OpenCOR codebase. For deeper exploration:
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.