Skip to content

AGENTS.md

Latest commit

 

History

History
91 lines (61 loc) · 5.11 KB

AGENTS.md

File metadata and controls

91 lines (61 loc) · 5.11 KB

Open Data Ensemble (ODE) — AI and developer guide

This monorepo contains the core platform for offline-first data collection and synchronization. Use this file when you work across packages or need the big picture. For deep dives, open the AGENTS.md in the package you are changing.

Published architecture (users and external readers): Architecture overview on opendataensemble.org.

Ecosystem map

ODE is a clearinghouse model: data is collected on devices, synchronized through Synkronus, and is intended to flow through the system for local analysis and stewardship—not to live only on the server.

  • Formulus — React Native mobile app: runs forms (JSON Forms) and custom app bundles in WebViews, offline-first, syncs with Synkronus.
  • Formulus Formplayer — React web app embedded in Formulus: renders forms inside a WebView; shares the same bridge contract as custom apps.
  • Synkronus — Go backend: auth, sync, app bundle distribution, export, shared HTTP API.
  • Synkronus Portal — Web admin UI (React + Vite): same API as other clients; no privileged backend channel.
  • Synkronus CLI — synk command-line client: automation, bundles, sync, export.
flowchart LR
  Formulus[Formulus_RN]
  Formplayer[Formulus_Formplayer]
  Synkronus[Synkronus_API]
  Portal[Portal]
  CLI[CLI]
  Formulus -->|sync| Synkronus
  Portal -->|same_API| Synkronus
  CLI -->|same_API| Synkronus
  Formulus -->|hosts_WebView| Formplayer
Loading

Design principle: One backend, many clients — prefer the public API for all user-facing tools.

User profiles (what to optimize for)

Profile Typical focus Where to work
Platform developer You are editing this repo: RN, Go, React, shared packages, CI. Package AGENTS.md below.
Custom app author You ship an HTML/JS/CSS app bundle and JSON forms for Formulus; you may not clone this monorepo. Custom app template (AI + author context) and documentation.

Do not assume custom app authors have local checkouts of ODE or internal example repos.

Monorepo layout

Package Role Stack Agent guide
formulus Mobile runtime, WebViews, native bridge React Native formulus/AGENTS.md
formulus-formplayer Form UI in WebView React, Vite, JSON Forms formulus-formplayer/AGENTS.md
synkronus Sync API and coordination Go synkronus/AGENTS.md
synkronus-cli CLI for API operations Go synkronus-cli/AGENTS.md
synkronus-portal Web administration React, TypeScript, Vite synkronus-portal/AGENTS.md
packages/tokens Design tokens (@ode/tokens) Style Dictionary packages/tokens/AGENTS.md
packages/components Shared UI (@ode/components) React packages/components/AGENTS.md

Cross-cutting contracts

  • Formulus ↔ WebView (custom apps + formplayer): formulus/src/webview/FormulusInterfaceDefinition.ts is the source of truth for the injected JavaScript API. Formplayer copies a synced TypeScript snapshot via npm run sync-interface in formulus-formplayer (see formulus-formplayer/AGENTS.md).
  • Shared UI tokens: Install tokens before components / formplayer where the docs require it (see package READMEs and formplayer AGENTS).

CI and code quality

Planned (not shipped here)

Do not implement or assume APIs for these as if they were in-repo unless issues/specs say otherwise:

  • ODE Custodian — local data stewardship and correction workflows (roadmap; often CLI-first).
  • ODE Workshop — desktop dev environment for bundles/forms (roadmap).

See product roadmap context and organization roadmaps on GitHub.

Custom app authors (pointer)

Authoritative public documentation: opendataensemble.org.

Optional AI-focused context (no ODE clone required): custom_app on GitHub (README.md, AGENTS.md, CONTEXT_*.md).