Running and reviewing a synthetic Delphi study

Start a trusted local session

For a local instance with one fixed synthetic identity:

# repo and actor come from trusted server-side demonstration setup.
app <- delphyrApp::run_app(repo, actor, language = "en")
shiny::runApp(app, host = "127.0.0.1")

The caller owns the lifetime of a directly supplied connection. All sessions of this instance use the same fixed actor; this is not a multi-user login. Never resolve identity or roles from browser fields or URL parameters.

A trusted host can instead supply a connection and identity resolver for each session. This example shows the contract; its deliberate error marks the host-specific identity adapter that still needs to be supplied:

make_repository <- function() {
  delphyr::connect_repository(
    host = "127.0.0.1", port = 55439, dbname = "delphyr",
    user = "delphyr_runtime", environment = "development"
  )
}
resolve_actor <- function(session, repo) {
  stop("Configure a verified server-side identity adapter before use")
}
app <- delphyrApp::run_app(
  repo_factory = make_repository,
  actor_factory = resolve_actor,
  language = "en"
)

Factory-created connections close when their session ends. Failed identity resolution ends the session before service access. The factory contract does not by itself qualify an OIDC gateway. Local gateway evidence and the remaining stock Shiny Server OSS transport limitations are documented separately.

Read, respond, and submit

Choose a study and an assigned round, load the questionnaire, and read the stored study information. Record consent explicitly. Ratings have no preselected midpoint. A field can instead use a special response category permitted by its scale.

A settled, complete response is saved automatically after a short pause; Save now saves it at once. Saved appears only after a committed revision and server timestamp return; until then the field reads Unsaved change. A failed save preserves the pending form value. A revision conflict stops automatic saving for that field: load the stored response deliberately and review it; automatic overwriting is not offered.

The progress count means confirmed response fields. Final submission first saves complete pending entries and is refused while any field remains unconfirmed. The service checks consent, ownership, rights, deadline, required fields, and the exact revision set again. A successful submission returns a durable receipt and ends editing for that round.

During connection loss, the interface must not imply that changes are saved. The tested disconnect/reload path restores the last committed value. It does not provide an offline editor or preserve unsaved text in browser storage.

Review rounds, feedback, and reports

Managers inspect the instrument and round state. A transition needs a reason and confirmation; the service rechecks the instrument hash and authority. Freeze a closed round before queuing analysis. A separate worker processes analysis and export jobs. Use Check operation to refresh their status.

Preview the exact feedback candidate before approving release. Released feedback can be assigned to an unopened next round. The panel sees approved aggregates and its own prior answers, with changed-wording notices where applicable. Bilingual instrument CSVs are validated and previewed before round preparation; interface language support does not create missing translations.

Managers can also inspect immutable protocol versions, upload a complete replacement JSON protocol, review field changes, and explicitly approve an amendment for future rounds. Existing rounds retain their original protocol. This is technical versioning, not an institutional or ethical approval.

Downloads recheck authority and integrity. The numeric research profile contains the snapshot, protocol, results, provenance, dictionary, instrument texts, and an HTML report. The worker uses a trusted Quarto template when its optional runtime is available. Otherwise a basic HTML fallback is labelled; a real render failure remains a failed job. Qualitative originals and individual free-text answers are excluded. Missing author information is not invented.

Preserve sources and review editorial work

Editors keep synthetic originals and create separate redactions or summaries with a reason. Summaries are labelled as summaries, not quotations. Another authorized person reviews the exact version before release.

Theme versions, inclusion/exclusion coding, source links, and item splits or merges preserve their provenance. Linking a source does not import an instrument item. Hidden interface sections never replace service-level authorization.

Import contacts without granting access

Coordinators can preview synthetic UTF-8 contact CSVs and inspect blocking row/column issues. Duplicate references, duplicate addresses, and ambiguous local-part case variants require correction and a new preview. Normal trailing LF or CRLF file terminators are supported without changing the uploaded hash.

Explicit approval imports the whole reviewed file atomically and returns a receipt for unbound invitation drafts. It creates no account, consent, response link, or round enrollment. Separate invitation services require approval of an existing stable issuer/subject identity; the complete invitation browser journey is not established by this CSV workflow.

Approve synthetic campaigns

Coordinators choose exact study pseudonyms and final message text. The resulting preview binds both content and recipients. A change requires a new preview; release needs explicit confirmation and a reason.

A separate worker writes only local test receipts. It rechecks participation, rights, withdrawal, and—for reminders—whether submission already occurred. The interface sends no email. Cancellation stops remaining processing without deleting existing receipts. An expired in-flight lease becomes delivery_unknown and is not blindly retried.

Design and remaining qualification

The interface uses system fonts, visible labels, keyboard focus, responsive forms, and live status regions. Language changes must preserve pending values; color alone does not communicate status. Permission-filtered navigation retains open forms when moving between study sections.

These are design choices and specific local checks, not formal accessibility certification. Assistive technologies, the complete cross-browser matrix, autosave, production login, external mail, and operational approval remain separate gates. Service injection supports focused module tests without a database; those tests do not replace actual PostgreSQL and browser evidence.