Skip to content
This repository was archived by the owner on Sep 26, 2026. It is now read-only.

Commit b6c8f9f

Browse files
r0ssingcursoragent
r0ssing
and
cursoragent
authored
docs: v1.1.0 refresh, Community Days announce (#28)
* docs(formplayer): document mobile UX and bridge API pack * docs: document sub-observation itemLabel and addButtonLabel Describe optional schema itemLabel and ui.json addButtonLabel override for embedded repeat add-button copy. Co-authored-by: Cursor <cursoragent@cursor.com> * formplayer, updated docs * v1.1.0 docs refresh * announce community days * typos --------- Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 1794c74 commit b6c8f9f

31 files changed

Lines changed: 1169 additions & 35 deletions

‎docs/development/architecture.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,22 @@ Go command-line utility providing:
8383
- Go 1.24+
8484
- Cobra CLI framework
8585

86+
### ODE Desktop
87+
88+
Tauri desktop application providing:
89+
90+
- **Local observation store**: SQLite per profile workspace
91+
- **Sync console**: Pull, push, conflict visibility, index rebuild
92+
- **Workbench**: Bundle download, form preview, custom app embed
93+
- **Developer mode**: Local custom app mirror for iteration
94+
95+
**Technology Stack:**
96+
- Tauri 2 (Rust)
97+
- React, TypeScript, Vite
98+
- Embedded formplayer
99+
100+
See [ODE Desktop Development](/development/ode-desktop-development).
101+
86102
## Data Flow
87103

88104
### Observation Creation

‎docs/development/ode-desktop-development.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
sidebar_position: 7
3+
---
4+
5+
# ODE Desktop Development
6+
7+
Complete guide for developing **ODE Desktop** from the ODE monorepo.
8+
9+
## Prerequisites
10+
11+
- **Node.js** 20+ and **pnpm** 10+
12+
- **Rust** toolchain ([rustup](https://rustup.rs/))
13+
- Platform build tools per [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/)
14+
15+
Install shared design tokens before the desktop package:
16+
17+
```bash
18+
cd packages/tokens && pnpm install && pnpm run build && cd ../..
19+
```
20+
21+
## Local development setup
22+
23+
```bash
24+
cd desktop
25+
pnpm install
26+
pnpm tauri dev
27+
```
28+
29+
:::warning Use the Tauri window
30+
31+
`pnpm tauri dev` opens the **Tauri desktop window** with the Rust backend. Do not use a regular browser at `http://localhost:1420` — IPC commands such as `invoke` only work inside the Tauri shell.
32+
33+
:::
34+
35+
For frontend-only work without Tauri IPC:
36+
37+
```bash
38+
pnpm dev
39+
```
40+
41+
This starts the Vite dev server only; most Data management and Workbench features require `pnpm tauri dev`.
42+
43+
## Scripts
44+
45+
| Script | Purpose |
46+
|--------|---------|
47+
| `pnpm dev` | Vite dev server (frontend only) |
48+
| `pnpm build` | Typecheck + Vite production build |
49+
| `pnpm build:formplayer` | Build `formulus-formplayer` and copy into `public/formplayer_dist/` |
50+
| `pnpm build:tauri` | Prepare Formplayer assets, then build the desktop frontend |
51+
| `pnpm tauri build` | Full desktop bundle (runs `build:tauri` first) |
52+
| `pnpm tauri dev` | Development with hot reload in the Tauri shell |
53+
| `pnpm lint` / `pnpm lint:fix` | ESLint |
54+
| `pnpm format` / `pnpm format:check` | Prettier |
55+
| `pnpm test` | Vitest unit and component tests |
56+
| `pnpm typecheck` | `tsc --noEmit` |
57+
| `pnpm copy:formplayer` | Copy existing `formulus-formplayer/build/` into `public/formplayer_dist/` |
58+
59+
From `formulus-formplayer/`, `pnpm run build:copy` builds formplayer and copies assets to Formulus and ODE Desktop in one step.
60+
61+
### Rust backend
62+
63+
```bash
64+
cd desktop/src-tauri
65+
cargo test
66+
cargo fmt
67+
cargo clippy
68+
```
69+
70+
## Formplayer integration
71+
72+
ODE Desktop embeds the same formplayer bundle as Formulus. Production builds copy formplayer into `public/formplayer_dist/`.
73+
74+
After changing formplayer or the Formulus bridge contract:
75+
76+
1. Update `formulus/src/webview/FormulusInterfaceDefinition.ts` (source of truth).
77+
2. Run `pnpm run sync-interface` in `formulus-formplayer`.
78+
3. Rebuild and copy: `pnpm run build:copy` from `formulus-formplayer/`, or `pnpm build:formplayer` from `desktop/`.
79+
80+
## OpenAPI client
81+
82+
The desktop app regenerates a TypeScript Synkronus client from `synkronus/openapi/synkronus.yaml`:
83+
84+
```bash
85+
cd desktop
86+
pnpm codegen:synk-client
87+
```
88+
89+
CI fails if the generated client does not match the OpenAPI spec.
90+
91+
## Developer mode (user-facing)
92+
93+
To test a local custom app build against a profile workspace, use **Workbench developer mode**. See:
94+
95+
- [ODE Desktop developer mode](/docs/guides/ode-desktop-developer-mode) — user guide
96+
- [ODE Desktop reference](/docs/reference/ode-desktop) — `bundles/dev-local/` paths and bridge behavior
97+
98+
## Project layout
99+
100+
| Path | Role |
101+
|------|------|
102+
| `desktop/src/` | React UI (pages, components, store) |
103+
| `desktop/src-tauri/` | Rust backend (SQLite, sync, bundle apply, dev mirror) |
104+
| `desktop/public/formplayer_dist/` | Embedded formplayer bundle |
105+
| `desktop/public/formulus-injection.js` | Bridge injection for custom app and form preview |
106+
107+
## Contributing
108+
109+
- Follow [Conventional Commits](https://www.conventionalcommits.org/)
110+
- Run `pnpm lint`, `pnpm format:check`, and `pnpm test` before pushing
111+
- PRs touching `desktop/**` trigger the ODE Desktop GitHub Actions workflow
112+
113+
## Related documentation
114+
115+
- [ODE Desktop reference](/docs/reference/ode-desktop) — component overview
116+
- [Installing ODE Desktop](/docs/getting-started/installation/installing-ode-desktop)
117+
- [Formplayer development](/development/formplayer-development)
118+
- [Building and testing](/development/building-testing)

‎docs/development/setup.md‎

Lines changed: 2 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -142,22 +142,9 @@ pnpm run format:check
142142

143143
## ODE Desktop Development
144144

145-
### Setup
146-
147-
```bash
148-
cd packages/tokens && pnpm install && pnpm run build && cd ../..
149-
cd desktop
150-
pnpm install
151-
```
152-
153-
### Running
154-
155-
```bash
156-
pnpm run dev # Vite dev server
157-
pnpm run build:tauri # Build formplayer assets + desktop + Tauri app
158-
```
145+
See [ODE Desktop Development](/docs/development/ode-desktop-development) for setup, scripts, and Formplayer integration.
159146

160-
See [ODE Desktop developer mode](/docs/guides/ode-desktop-developer-mode) for local custom app iteration.
147+
For testing a local custom app build in the Workbench, see [ODE Desktop developer mode](/docs/guides/ode-desktop-developer-mode).
161148

162149
## Synkronus Development
163150

‎docs/getting-started/architecture-overview.md‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ ODE (Open Data Ensemble) is a comprehensive platform for mobile data collection
88

99
## Core Components
1010

11-
ODE consists of four main components that work together to provide a complete data collection solution:
11+
ODE consists of these main components that work together to provide a complete data collection solution:
1212

1313
### Synkronus Server
1414
The backend server responsible for:
@@ -39,6 +39,25 @@ Command-line utility for:
3939
- **User Administration**: Manage users and permissions
4040
- **Server Administration**: Maintenance and monitoring tasks
4141

42+
### ODE Desktop
43+
44+
Desktop application (Tauri + React + Rust) for data stewardship and app development:
45+
46+
- **Data management**: Pull, inspect, edit, import, and sync observations against Synkronus
47+
- **Forms / app workbench**: Download app bundles, preview forms, and test custom apps
48+
- **Developer mode**: Mirror a local custom app build without replacing the Synk-downloaded bundle
49+
- **Same public API**: Uses Synkronus REST API — no privileged desktop channel
50+
51+
Introduced in **ODE v1.1.0**. See [ODE Desktop reference](/docs/reference/ode-desktop) and [install guide](/docs/getting-started/installation/installing-ode-desktop).
52+
53+
### Synkronus Portal
54+
55+
Web-based administrative interface (also embedded in the Synkronus binary at `/portal`):
56+
57+
- **User and bundle management**
58+
- **Observation viewing and export**
59+
- **Same API** as Formulus, CLI, and ODE Desktop
60+
4261
## Architecture Patterns
4362

4463
### Embedded Portal Architecture

‎docs/getting-started/installation/installing-ode-desktop.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# Installing ODE Desktop
6+
7+
Complete guide for installing **ODE Desktop** on Windows, macOS, and Linux.
8+
9+
:::info ODE v1.1.0
10+
11+
ODE Desktop is part of the **ODE v1.1.0** release. Pre-built installers are published on [GitHub Releases](https://github.com/OpenDataEnsemble/ode/releases).
12+
13+
:::
14+
15+
## Overview
16+
17+
ODE Desktop is a native desktop application (Tauri) for:
18+
19+
- **Data management** — inspect, edit, import, and sync observations with Synkronus
20+
- **Forms / app workbench** — download app bundles, preview forms, and test custom apps
21+
22+
Choose the installation method that fits your role:
23+
24+
| Method | Best for |
25+
|--------|----------|
26+
| **GitHub Release** | Data stewards and app authors who want a ready-to-run installer |
27+
| **Build from source** | Contributors and early adopters working from the ODE monorepo |
28+
29+
## System requirements
30+
31+
| Platform | Requirements |
32+
|----------|--------------|
33+
| **Windows** | Windows 10 or 11; [WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) (usually pre-installed) |
34+
| **macOS** | Recent macOS; Xcode command-line tools for source builds |
35+
| **Linux** | WebKitGTK and related packages per [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/) |
36+
37+
## Method 1: GitHub Releases (recommended)
38+
39+
1. Open [OpenDataEnsemble/ode releases](https://github.com/OpenDataEnsemble/ode/releases).
40+
2. Select the **v1.1.0** release (or the latest stable tag).
41+
3. Download the artifact for your platform:
42+
43+
| Platform | Typical artifact |
44+
|----------|------------------|
45+
| Windows | `.msi` installer |
46+
| macOS | `.dmg` or `.app` bundle |
47+
| Linux | AppImage, `.deb`, or similar |
48+
49+
4. Run the installer or extract the bundle and launch **ODE Desktop**.
50+
51+
:::note Installer script
52+
53+
A curl-style installer script (`scripts/install-ode-desktop.sh`) exists in the monorepo as a placeholder for future one-line installs. Until it is wired to release asset URLs, use GitHub Releases directly.
54+
55+
:::
56+
57+
## Method 2: Build from source
58+
59+
For development or when no pre-built artifact is available for your platform:
60+
61+
### Prerequisites
62+
63+
- **Node.js** 20+ and **pnpm** 10+
64+
- **Rust** toolchain ([rustup](https://rustup.rs/))
65+
- Platform build tools (see [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/))
66+
67+
### Build steps
68+
69+
```bash
70+
git clone https://github.com/OpenDataEnsemble/ode.git
71+
cd ode/desktop
72+
pnpm install
73+
pnpm tauri build
74+
```
75+
76+
`pnpm tauri build` runs the full pipeline: Formplayer assets are prepared, the frontend is built, and Tauri packages the native app. Installers or bundles appear under `desktop/src-tauri/target/release/bundle/`.
77+
78+
### Development run
79+
80+
To run with hot reload during development:
81+
82+
```bash
83+
cd ode/desktop
84+
pnpm install
85+
pnpm tauri dev
86+
```
87+
88+
:::warning Use the Tauri window
89+
90+
`pnpm tauri dev` opens the **Tauri desktop window**. Do not use a regular browser at `http://localhost:1420` — IPC commands such as `invoke` only work inside the Tauri shell.
91+
92+
:::
93+
94+
## First launch
95+
96+
1. Open **ODE Desktop**.
97+
2. Switch to **Data management** mode (if not already selected).
98+
3. On **Profiles**, add or select a profile with your Synkronus server URL.
99+
4. **Authenticate** with your Synkronus credentials.
100+
5. On **Sync**, run **Pull** to download observations, or **Download & apply** an app bundle from **Workbench → Bundles**.
101+
102+
## Next steps
103+
104+
- [ODE Desktop user guide](/docs/using/ode-desktop/) — screen-by-screen usage
105+
- [ODE Desktop reference](/docs/reference/ode-desktop) — architecture and workspace layout
106+
- [ODE Desktop developer mode](/docs/guides/ode-desktop-developer-mode) — test a local custom app build
107+
- [ODE Desktop development](/docs/development/ode-desktop-development) — contributor setup
108+
109+
## Troubleshooting
110+
111+
| Issue | Suggestion |
112+
|-------|------------|
113+
| App won't start on Linux | Install WebKitGTK and dependencies from Tauri docs |
114+
| WebView2 missing on Windows | Install the [WebView2 runtime](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) |
115+
| Build fails on `pnpm tauri build` | Ensure Rust and platform prerequisites are installed; run `pnpm build:formplayer` first if Formplayer assets are missing |
116+
| Sync authentication fails | Verify server URL and credentials on **Profiles**; check server reachability on **Sync** |
117+
118+
For more help, see [Getting Help](/docs/community/getting-help) or the [forum](https://forum.opendataensemble.org).

0 commit comments

Comments
 (0)