Skip to content

README.md

Latest commit

 

History

History
100 lines (68 loc) · 7.18 KB

README.md

File metadata and controls

100 lines (68 loc) · 7.18 KB

ODE Desktop

ODE Desktop is the Open Data Ensemble desktop application (Tauri + React + Rust). It provides two modes:

Mode Purpose
Data management Pull, inspect, correct, and sync observations; import/export; conflicts and local workspace state.
Forms / app workbench Develop and test app bundles, embedded formplayer, and custom apps — aligned with Formulus and the shared WebView contract.

The internal Rust crate may still be named custodian; user-facing strings use ODE Desktop.

Who it is for

  • Field and data staff managing observations and sync (Data management).
  • Form and app authors testing bundles and custom apps against Synkronus before mobile deploy (Workbench).

Relationship to other ODE components: Synkronus (API), Formulus + formplayer (runtime parity), Portal and CLI (same public API — no privileged desktop channel). Long-form prose here is intended to be copy-friendly for opendataensemble.org documentation; keep user-facing sections free of repo-only trivia (put contributor notes under Development).

Install

Official builds are produced with pnpm tauri build (artifacts vary by OS: .msi, .dmg, .app, AppImage, .deb, etc.). When releases are published, attach those bundles to GitHub Releases and link them from project docs.

Prerequisites

  • Windows: WebView2 (usually present on current Windows 10/11).
  • Linux: WebKitGTK and related packages as required by Tauri prerequisites.
  • macOS: Xcode command-line tools for development builds.

A placeholder curl-style installer script is at scripts/install-ode-desktop.sh (to be wired to real release asset URLs). For early testing, run from source (below).

Quick start (development)

From the monorepo root:

cd desktop
pnpm install
pnpm dev

In another terminal:

cd desktop
pnpm tauri dev

Scripts

Script Purpose
pnpm dev Vite dev server (frontend).
pnpm build Typecheck + Vite production build.
pnpm build:formplayer Build ../formulus-formplayer and copy output into public/formplayer_dist/.
pnpm build:tauri Prepare Formplayer assets (build:formplayer) and then run the desktop frontend build.
pnpm tauri build Full desktop bundle; automatically runs pnpm build:tauri first, so the packaged app includes formplayer_dist.
pnpm lint / pnpm lint:fix ESLint.
pnpm format / pnpm format:check Prettier.
pnpm test Vitest (unit / component tests).
pnpm typecheck tsc --noEmit.
pnpm codegen:synk-client Regenerate TypeScript client from Synkronus OpenAPI.
pnpm copy:formplayer Copy ../formulus-formplayer/build/ → public/formplayer_dist/. Prefer from formulus-formplayer/: npm run build:copy (build + Formulus + desktop copy).

Rust (backend)

cd src-tauri
cargo test
cargo fmt
cargo clippy

OpenAPI client

Configuration is in openapi.client.config.json (paths relative to desktop/):

  • Default spec: ../synkronus/openapi/synkronus.yaml
  • Output: src/generated/synkronus-client

Override at generation time:

  • OPENAPI_SPEC_RELATIVE_PATH
  • OPENAPI_OUTPUT_RELATIVE_PATH

CI regenerates the client and fails if the repo does not match (ode-desktop workflow).

Architecture pointers

  • Bridge contract: formulus/src/webview/FormulusInterfaceDefinition.ts — source of truth for formulusAPI / postMessage. After changes, run sync-interface in formulus-formplayer and mirror behavior in the desktop WebView host.
  • Form preview host (Workbench → Form preview): public/formulus-injection.js + iframe shim; parent handles postMessage in src/lib/formPreviewBridge.ts (explicit matrix per FormulusInjectionScript request type; device APIs including camera, audio, and video are stubbed in preview; observations + URIs use Tauri where applicable). Nested sub-observation flows (openFormplayer + options.subObservationMode) open a stacked Form preview iframe and resolve the parent promise with FormCompletionResult without persisting the child as a top-level observation.
  • Bundle extensions: merge rules for forms/ext.json and forms/{form}/ext.json follow Formulus ExtensionService; see src/lib/bundleResolution.ts.
  • Embedded formplayer: production build copied into public/formplayer_dist/; load in a WebView with the same FormInitData expectations as mobile (see src/lib/formplayerHost.ts for placeholder types).

Application icon (Linux)

Bundled icons live under src-tauri/icons/ and are referenced from src-tauri/tauri.conf.json bundle.icon. Misplaced iOS-style asset folders are not used for Tauri Linux bundles and have been removed to avoid confusion. For deb/AppImage installs, verify the packaged .desktop file Icon= entry resolves on Ubuntu/GNOME (dash, dock, Alt+Tab).

Contributing

Conventional Commits; run pnpm lint, pnpm format:check, and pnpm test before pushing. PRs touching desktop/** trigger the ODE Desktop GitHub Actions workflow (see .github/CICD.md).