Governed study record
Delphi Studio treats the backend study record as the production source of truth. The browser presents and edits that record, but browser storage cannot independently establish protocol, recruitment, consent, COI, launch, or amendment state.
This boundary matters because a research record must remain coherent when multiple collaborators work at once, a participant follows an emailed link, an email provider retries a callback, or an investigator proposes a post-launch change.
Authority and concurrency
Every governed mutation follows the same contract:
- Authenticate the actor.
- Confirm organization and study membership.
- Authorize the requested action.
- Compare the expected revision with the current study revision.
- Validate and normalize the proposed result.
- Commit the study change and audit event together.
- Return the new authoritative revision.
When two collaborators edit the same revision, the first valid commit advances the record. A later stale write is rejected as a conflict rather than silently overwriting the first change. The client then refreshes the current record so the user can review and reapply their change.
Offline or cached data is clearly non-authoritative. It can support a resilient read experience, but it cannot advance a governed workflow.
Authentication and authorization
Researcher access uses authenticated organization accounts and study-scoped roles. Panelists use purpose-bound access for their own invitation, consent, COI, enrollment, withdrawal, and rating actions. See Collaboration & roles for researcher permissions and Panelist experience for participant access.
The main boundaries are:
- users can access only organizations and studies in which they have membership;
- permissions are checked on the server for every read and mutation;
- sensitive operations such as identity reveal require a reason and an audit event;
- panelist access is restricted to the matching study relationship and purpose; and
- production authentication fails closed when required credentials or trusted identity integration are absent.
An interface hiding a button is not an authorization control. The server enforces the same policy even when a request is made directly.
Protocol documents
Protocol uploads are validated as files, not trusted as browser metadata. The document service checks:
- the filename and allowed extension;
- the declared media type;
- the file's identifying bytes;
- the configured size limit; and
- a SHA-256 digest of the accepted content.
PDF, DOCX, and ODT are supported by the current study workflow. Production storage should remain private and add malware scanning, encryption, retention rules, access logging, backups, and deletion policy appropriate to the study and jurisdiction.
The digest and recorded protocol version bind consent and later amendments to a specific document state.
Item and panel imports
CSV imports are service operations with a preview-and-validate boundary. They enforce required columns, normalize values, detect duplicates, cap file and row size, and report row-level problems before the study is mutated.
| Import | Minimum fields | Additional controls |
|---|---|---|
| Items | statement, domain | Empty values, duplicate statements, domain consistency |
| Panel | email, first_name, last_name, specialty, institution | Email validity, duplicate rows, existing study relationships |
An import is not a recruitment send. Panel selection, invitation request, delivery, acceptance, consent, COI, and enrollment remain distinct records so the recruitment flow can be reconstructed later.
Email delivery
Participant email is queued through an outbox. This keeps an external delivery provider outside the study transaction while preserving a durable intent to send.
- A permitted study command creates a queued message and a hashed, one-time access credential.
- An authenticated email worker leases one message.
- The worker receives the full delivery link only while handling that message.
- The provider reports delivery or failure through an authenticated callback.
- Repeated callbacks with the same terminal result are idempotent.
The study does not claim that an invitation was delivered merely because a researcher clicked a button. Provider delivery evidence advances the recruitment projection. Failed invitations can be retried without reviving or duplicating the previous failed credential.
Consent, COI, and enrollment
Panelist onboarding is an ordered workflow:
Consent evidence includes the protocol or consent version, attestation, signature name, actor, and timestamp. A COI record includes the declaration, conflict flag, attestation, actor, and timestamp. Enrollment is refused until the required evidence exists.
A material protocol amendment can trigger notification or re-consent according to the configured policy. When re-consent is mandatory, a new round cannot open while required acknowledgments remain outstanding.
Launch and amendment transitions
Lifecycle state cannot be changed through a generic study update. Explicit commands enforce their own preconditions:
- Request invitations requires a complete preflight and no critical blockers.
- Open Round 1 requires recruiting state and the configured enrolled, consented, and COI thresholds.
- Submit amendment requires an allowed patch and substantive rationale.
- Approve or reject amendment requires the appropriate review permission.
A submitted amendment remains pending and does not alter the active study. Approval applies it as a new revision; rejection preserves the proposal and decision evidence without changing the active protocol.
Audit transaction
For a governed mutation, the resulting study revision and its audit event are one transaction. Audit evidence identifies:
- actor and role;
- action and affected entity;
- previous and resulting revision;
- occurrence time; and
- bounded metadata needed to interpret the transition.
This transactional history complements frozen launch, round-rule, feedback, protocol, and consent snapshots. See Audit trail for the evidence model and export guidance.
Production deployment boundary
The authority contract is independent of infrastructure vendor. A production deployment should implement it with:
- a transactional database with revision checks;
- private object storage and malware scanning;
- trusted OIDC or SAML identity integration and account provisioning;
- a durable email worker with authenticated, idempotent callbacks;
- managed secrets, rate limiting, structured logs, metrics, and tracing; and
- tested backup, retention, and disaster-recovery procedures.
Development adapters are useful for local verification, but browser storage, a single-process JSON file, local uploads, development sessions, or simulated delivery are not substitutes for those production controls.