Hosted Backend
PsyCloud can be used offline for authoring and preview, but real participant collection uses the hosted backend. The backend is the control plane for researchers and the runtime host for participants: it stores study metadata, immutable releases, run links, sessions, telemetry, counterbalancing state, recruitment bindings, assets, and export jobs.
Studio authoring, SDK authoring, Project Bundle validation, compile, inspect, and workbench checks work locally. Publishing releases, creating active runs, joining through study links, ingesting telemetry, recruitment, monitoring, and data export require the backend.
Local vs hosted
| Workflow | Local only | Hosted backend |
|---|---|---|
| Author and preview a study | Yes | Optional |
| Validate, inspect, and compile a Project Bundle | Yes | Optional |
| Publish an immutable release | No | Yes |
| Create a run and share participant links | No | Yes |
| Allocate counterbalanced assignments | Preview simulation only | Yes, with persisted allocation state |
| Store participant telemetry and sessions | No | Yes |
| Monitor sessions and export CSV/JSON/snapshots | No | Yes |
| Recruit through Prolific or MTurk | No | Yes |
Use Running Studies & Recruitment for the researcher workflow and the full CLI reference for exact command flags.
Control-plane model
The backend schema centers on the same lifecycle Studio shows.
| Object | What it represents | Notes |
|---|---|---|
| Workspace | A research group or tenant | Owns projects, connectors, storage mode, and membership. |
| Project | A container inside a workspace | Groups related studies. |
| Study | The named research object | Holds drafts, bundles, runs, and counterbalance config. |
| StudyDraft | Editable authoring state | Stores IR, design recipe, semantics, and asset index. |
| Bundle | Immutable release | Content-addressed by bundleHash with IR, manifest lock, and asset manifest. |
| Run | Participant-facing deployment | Points at one bundle, has status, config, links, sessions, and datasets. |
| RunLink | Shareable entry code | Lets one run have per-channel links with caps/expiry/active state. |
| Session | One participant execution | Stores pseudonymous subject id, assignment, token hash, status, and timing. |
| TelemetryEvent | Runtime event envelope | Ordered by session sequence number and tied to run/session provenance. |
| Dataset / DataExport | Derived analysis outputs | CSV, JSON, and snapshot exports are generated from run/session events. |
| WorkspaceConnector | Recruitment credentials | Stores encrypted provider configuration for Prolific, MTurk, and future providers. |
Route families
The public API is mounted under /api unless noted.
| Family | What it powers |
|---|---|
/api/auth, /api/auth/oauth | Registration, login, refresh, logout, password reset, email verification, OAuth. |
/api/projects, /api/studies, /api/studies/:studyId/drafts | Workspace authoring and draft history. |
/api/studies/:studyId/bundles, /api/bundles | Publishing releases, bundle metadata, downloads, and preflight reports. |
/api/runs, /api/runs/:runId/links | Run creation, activation, pausing, completion, join URLs, and study links. |
/run, /s, /runtime/bundle.js | Participant entry, session bootstrap, completion, and runtime delivery. |
/api/telemetry, /ws/events | Runtime event ingest, cursor reads, session summaries, errors, and live streams. |
/api/monitor | Monitor dashboards, session details, review queues, and incremental polling. |
/api/assets | Asset upload, existence checks, and participant asset delivery. |
/api/exports | Dataset derivation, CSV/JSON/snapshot downloads, raw event exports, and QC. |
/api/runs/:runId/counterbalance/... | Persisted allocation, assignment status, epoch reports, and audit lookups. |
/api/workspaces/:workspaceId/connectors/... | Provider connector setup, webhook setup, reconciliation, and disabling. |
/api/webhooks | Provider webhook receipt and idempotency. |
Participant data path
- Researcher publishes
A draft or Project Bundle becomes an immutable Bundle with a content hash, runtime version, telemetry schema version, manifest index, and asset manifest.
- Researcher creates a run
The run points at the bundle and gets one or more RunLinks. Activation controls whether participants can join.
- Participant joins
/run/:coderesolves the link, allocates a session, assigns counterbalance state when needed, and redirects to/s/:sessionIdwith a session token. - Runtime boots
/runtime/bundle.jsloads the participant runtime, then/api/sessions/:sessionId/bootstrapreturns the bundle, assignment, and API endpoints for telemetry. - Events are stored
Runtime events are batched to
/api/telemetry/events; exports derive trial tables and raw event files from the stored envelopes.
Operations checklist
For a production-like deployment, the server refuses to start unless the security-critical configuration is explicit.
| Area | Required posture |
|---|---|
| Database | DATABASE_URL points at PostgreSQL. |
| JWT/session secrets | JWT_ACCESS_SECRET, JWT_REFRESH_SECRET, and JWT_SESSION_SECRET are set in production. |
| CORS | CORS_ORIGINS is an explicit allowlist in production, not *. |
| Public URLs | BASE_URL and FRONTEND_URL match the deployed API and Studio origins. |
| Storage | STORAGE_PROVIDER is local, s3, or minio; remote storage requires bucket, region, keys, and MinIO endpoint when used. |
EMAIL_PROVIDER=resend plus Resend key/from settings for real verification and reset email. | |
| OAuth | Google, GitHub, and ORCID credentials are optional; missing providers simply are not available. |
| Recruitment | Prolific and MTurk connectors are workspace-scoped and should be tested in sandbox before production collection. |
See Data Governance for retention and participant-data handling.
Alpha limits
- Hosted collection is the source of truth for participant data; local preview data is for debugging and is not exportable through the hosted Data perspective.
- Self-service deletion and retention controls are still alpha-era operations. Treat retained data as durable unless an operator or self-host administrator explicitly deletes it.
- BattleLab and preflight harness routes are development/verification surfaces, not researcher product workflows.
- A production deployment needs access control, explicit CORS, real secrets, managed database backups, object-storage lifecycle policy, and provider sandbox checks before collecting real participant data.