OpenDataEnsemble · najuna-brian · Jun 17, 2026 · Jun 15, 2026 · Jun 17, 2026 · Jun 17, 2026
diff --git a/docs/development/architecture.md b/docs/development/architecture.md
@@ -83,6 +83,22 @@ Go command-line utility providing:
 - Go 1.24+
 - Cobra CLI framework
 
+### ODE Desktop
+
+Tauri desktop application providing:
+
+- **Local observation store**: SQLite per profile workspace
+- **Sync console**: Pull, push, conflict visibility, index rebuild
+- **Workbench**: Bundle download, form preview, custom app embed
+- **Developer mode**: Local custom app mirror for iteration
+
+**Technology Stack:**
+- Tauri 2 (Rust)
+- React, TypeScript, Vite
+- Embedded formplayer
+
+See [ODE Desktop Development](/development/ode-desktop-development).
+
 ## Data Flow
 
 ### Observation Creation

diff --git a/docs/development/ode-desktop-development.md b/docs/development/ode-desktop-development.md
@@ -0,0 +1,118 @@
+---
+sidebar_position: 7
+---
+
+# ODE Desktop Development
+
+Complete guide for developing **ODE Desktop** from the ODE monorepo.
+
+## Prerequisites
+
+- **Node.js** 20+ and **pnpm** 10+
+- **Rust** toolchain ([rustup](https://rustup.rs/))
+- Platform build tools per [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/)
+
+Install shared design tokens before the desktop package:
+
+```bash
+cd packages/tokens && pnpm install && pnpm run build && cd ../..
+```
+
+## Local development setup
+
+```bash
+cd desktop
+pnpm install
+pnpm tauri dev
+```
+
+:::warning Use the Tauri window
+
+`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.
+
+:::
+
+For frontend-only work without Tauri IPC:
+
+```bash
+pnpm dev
+```
+
+This starts the Vite dev server only; most Data management and Workbench features require `pnpm tauri dev`.
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `pnpm dev` | Vite dev server (frontend only) |
+| `pnpm build` | Typecheck + Vite production build |
+| `pnpm build:formplayer` | Build `formulus-formplayer` and copy into `public/formplayer_dist/` |
+| `pnpm build:tauri` | Prepare Formplayer assets, then build the desktop frontend |
+| `pnpm tauri build` | Full desktop bundle (runs `build:tauri` first) |
+| `pnpm tauri dev` | Development with hot reload in the Tauri shell |
+| `pnpm lint` / `pnpm lint:fix` | ESLint |
+| `pnpm format` / `pnpm format:check` | Prettier |
+| `pnpm test` | Vitest unit and component tests |
+| `pnpm typecheck` | `tsc --noEmit` |
+| `pnpm copy:formplayer` | Copy existing `formulus-formplayer/build/` into `public/formplayer_dist/` |
+
+From `formulus-formplayer/`, `pnpm run build:copy` builds formplayer and copies assets to Formulus and ODE Desktop in one step.
+
+### Rust backend
+
+```bash
+cd desktop/src-tauri
+cargo test
+cargo fmt
+cargo clippy
+```
+
+## Formplayer integration
+
+ODE Desktop embeds the same formplayer bundle as Formulus. Production builds copy formplayer into `public/formplayer_dist/`.
+
+After changing formplayer or the Formulus bridge contract:
+
+1. Update `formulus/src/webview/FormulusInterfaceDefinition.ts` (source of truth).
+2. Run `pnpm run sync-interface` in `formulus-formplayer`.
+3. Rebuild and copy: `pnpm run build:copy` from `formulus-formplayer/`, or `pnpm build:formplayer` from `desktop/`.
+
+## OpenAPI client
+
+The desktop app regenerates a TypeScript Synkronus client from `synkronus/openapi/synkronus.yaml`:
+
+```bash
+cd desktop
+pnpm codegen:synk-client
+```
+
+CI fails if the generated client does not match the OpenAPI spec.
+
+## Developer mode (user-facing)
+
+To test a local custom app build against a profile workspace, use **Workbench developer mode**. See:
+
+- [ODE Desktop developer mode](/docs/guides/ode-desktop-developer-mode) — user guide
+- [ODE Desktop reference](/docs/reference/ode-desktop) — `bundles/dev-local/` paths and bridge behavior
+
+## Project layout
+
+| Path | Role |
+|------|------|
+| `desktop/src/` | React UI (pages, components, store) |
+| `desktop/src-tauri/` | Rust backend (SQLite, sync, bundle apply, dev mirror) |
+| `desktop/public/formplayer_dist/` | Embedded formplayer bundle |
+| `desktop/public/formulus-injection.js` | Bridge injection for custom app and form preview |
+
+## Contributing
+
+- Follow [Conventional Commits](https://www.conventionalcommits.org/)
+- Run `pnpm lint`, `pnpm format:check`, and `pnpm test` before pushing
+- PRs touching `desktop/**` trigger the ODE Desktop GitHub Actions workflow
+
+## Related documentation
+
+- [ODE Desktop reference](/docs/reference/ode-desktop) — component overview
+- [Installing ODE Desktop](/docs/getting-started/installation/installing-ode-desktop)
+- [Formplayer development](/development/formplayer-development)
+- [Building and testing](/development/building-testing)
diff --git a/docs/development/setup.md b/docs/development/setup.md
@@ -142,22 +142,9 @@ pnpm run format:check
 
 ## ODE Desktop Development
 
-### Setup
-
-```bash
-cd packages/tokens && pnpm install && pnpm run build && cd ../..
-cd desktop
-pnpm install
-```
-
-### Running
-
-```bash
-pnpm run dev          # Vite dev server
-pnpm run build:tauri  # Build formplayer assets + desktop + Tauri app
-```
+See [ODE Desktop Development](/docs/development/ode-desktop-development) for setup, scripts, and Formplayer integration.
 
-See [ODE Desktop developer mode](/docs/guides/ode-desktop-developer-mode) for local custom app iteration.
+For testing a local custom app build in the Workbench, see [ODE Desktop developer mode](/docs/guides/ode-desktop-developer-mode).
 
 ## Synkronus Development
 

diff --git a/docs/getting-started/architecture-overview.md b/docs/getting-started/architecture-overview.md
@@ -8,7 +8,7 @@ ODE (Open Data Ensemble) is a comprehensive platform for mobile data collection
 
 ## Core Components
 
-ODE consists of four main components that work together to provide a complete data collection solution:
+ODE consists of these main components that work together to provide a complete data collection solution:
 
 ### Synkronus Server
 The backend server responsible for:
@@ -39,6 +39,25 @@ Command-line utility for:
 - **User Administration**: Manage users and permissions
 - **Server Administration**: Maintenance and monitoring tasks
 
+### ODE Desktop
+
+Desktop application (Tauri + React + Rust) for data stewardship and app development:
+
+- **Data management**: Pull, inspect, edit, import, and sync observations against Synkronus
+- **Forms / app workbench**: Download app bundles, preview forms, and test custom apps
+- **Developer mode**: Mirror a local custom app build without replacing the Synk-downloaded bundle
+- **Same public API**: Uses Synkronus REST API — no privileged desktop channel
+
+Introduced in **ODE v1.1.0**. See [ODE Desktop reference](/docs/reference/ode-desktop) and [install guide](/docs/getting-started/installation/installing-ode-desktop).
+
+### Synkronus Portal
+
+Web-based administrative interface (also embedded in the Synkronus binary at `/portal`):
+
+- **User and bundle management**
+- **Observation viewing and export**
+- **Same API** as Formulus, CLI, and ODE Desktop
+
 ## Architecture Patterns
 
 ### Embedded Portal Architecture

diff --git a/docs/getting-started/installation/installing-ode-desktop.md b/docs/getting-started/installation/installing-ode-desktop.md
@@ -0,0 +1,118 @@
+---
+sidebar_position: 3
+---
+
+# Installing ODE Desktop
+
+Complete guide for installing **ODE Desktop** on Windows, macOS, and Linux.
+
+:::info ODE v1.1.0
+
+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).
+
+:::
+
+## Overview
+
+ODE Desktop is a native desktop application (Tauri) for:
+
+- **Data management** — inspect, edit, import, and sync observations with Synkronus
+- **Forms / app workbench** — download app bundles, preview forms, and test custom apps
+
+Choose the installation method that fits your role:
+
+| Method | Best for |
+|--------|----------|
+| **GitHub Release** | Data stewards and app authors who want a ready-to-run installer |
+| **Build from source** | Contributors and early adopters working from the ODE monorepo |
+
+## System requirements
+
+| Platform | Requirements |
+|----------|--------------|
+| **Windows** | Windows 10 or 11; [WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) (usually pre-installed) |
+| **macOS** | Recent macOS; Xcode command-line tools for source builds |
+| **Linux** | WebKitGTK and related packages per [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/) |
+
+## Method 1: GitHub Releases (recommended)
+
+1. Open [OpenDataEnsemble/ode releases](https://github.com/OpenDataEnsemble/ode/releases).
+2. Select the **v1.1.0** release (or the latest stable tag).
+3. Download the artifact for your platform:
+
+   | Platform | Typical artifact |
+   |----------|------------------|
+   | Windows | `.msi` installer |
+   | macOS | `.dmg` or `.app` bundle |
+   | Linux | AppImage, `.deb`, or similar |
+
+4. Run the installer or extract the bundle and launch **ODE Desktop**.
+
+:::note Installer script
+
+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.
+
+:::
+
+## Method 2: Build from source
+
+For development or when no pre-built artifact is available for your platform:
+
+### Prerequisites
+
+- **Node.js** 20+ and **pnpm** 10+
+- **Rust** toolchain ([rustup](https://rustup.rs/))
+- Platform build tools (see [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/))
+
+### Build steps
+
+```bash
+git clone https://github.com/OpenDataEnsemble/ode.git
+cd ode/desktop
+pnpm install
+pnpm tauri build
+```
+
+`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/`.
+
+### Development run
+
+To run with hot reload during development:
+
+```bash
+cd ode/desktop
+pnpm install
+pnpm tauri dev
+```
+
+:::warning Use the Tauri window
+
+`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.
+
+:::
+
+## First launch
+
+1. Open **ODE Desktop**.
+2. Switch to **Data management** mode (if not already selected).
+3. On **Profiles**, add or select a profile with your Synkronus server URL.
+4. **Authenticate** with your Synkronus credentials.
+5. On **Sync**, run **Pull** to download observations, or **Download & apply** an app bundle from **Workbench → Bundles**.
+
+## Next steps
+
+- [ODE Desktop user guide](/docs/using/ode-desktop/) — screen-by-screen usage
+- [ODE Desktop reference](/docs/reference/ode-desktop) — architecture and workspace layout
+- [ODE Desktop developer mode](/docs/guides/ode-desktop-developer-mode) — test a local custom app build
+- [ODE Desktop development](/docs/development/ode-desktop-development) — contributor setup
+
+## Troubleshooting
+
+| Issue | Suggestion |
+|-------|------------|
+| App won't start on Linux | Install WebKitGTK and dependencies from Tauri docs |
+| WebView2 missing on Windows | Install the [WebView2 runtime](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) |
+| Build fails on `pnpm tauri build` | Ensure Rust and platform prerequisites are installed; run `pnpm build:formplayer` first if Formplayer assets are missing |
+| Sync authentication fails | Verify server URL and credentials on **Profiles**; check server reachability on **Sync** |
+
+For more help, see [Getting Help](/docs/community/getting-help) or the [forum](https://forum.opendataensemble.org).