How SeqDesk Works

1. A researcher raises a sequencing order

The researcher fills in the order wizard and submits. The order gets a number in the form ORD-YYYYMMDD-NNNN (the counter restarts each day) and moves from DRAFT to SUBMITTED.

Order status is a three-value ladder, not an enum in the database:

A researcher may only make the one transition DRAFT → SUBMITTED; anything else returns Invalid status transition. Facility admins may move an order backwards.

COMPLETED is usually reached without anyone clicking anything: whenever a file is assigned, SeqDesk re-checks the order, and if it is SUBMITTED, has at least one sample, and every sample has a read with a file, it flips the order to COMPLETED and writes the status note “Automatically completed - all samples have sequencing files”.

2. The facility sequences the samples

Samples carry their own facility-side status, independent of the order status, so a facility can track progress per sample rather than per order:

WAITING → PROCESSING → SEQUENCED → QC_REVIEW → READY, with ISSUE as the escape hatch. New samples start at WAITING.

If the facility uses the Sequencing Run surface, it also records the physical run: platform, instrument, run date, folder path, Q30 score, cluster density, pass-filter percentage, and the barcode each sample carried.

3. FASTQ files get attached to samples

There are three ways data reaches a sample. All three end with a Read row.

File scan (the default). After sequencing finishes, an admin opens the order’s Sequencing Data area and uses the Associate view to browse the configured data directory. SeqDesk lists candidate FASTQ files, recognises _R1/_R2 (and _1/_2) naming to pair them, and the admin links them to samples. This requires the order to be SUBMITTED or COMPLETED — attempting it on a DRAFT order returns Sequencing Order status 'DRAFT' does not allow file assignment.

Direct upload. Files can be uploaded into the order through the same Sequencing Data area, tracked as SequencingUpload rows with an expected size and a checksum, then promoted to reads.

Live MinKNOW stream ingest (Oxford Nanopore). For ONT runs an admin can attach a running MinKNOW sequencing run to an order and have reads ingested while MinKNOW writes them, matched to samples by barcode. A long-lived stream-monitor daemon, running outside the web process, watches MinKNOW’s output root. Configure it at Settings → MinKNOW Stream (/admin/minknow-stream); drive an individual order from its Sequencing Data → Stream view. If the daemon is not running, nothing is ingested no matter how the configuration looks. The StreamRun, StreamIngestedFile and StreamRunEvent records track each live session.

4. Reads are classified, and only cleaned reads are delivered

Every read carries a dataClass:

Reads also carry isActive. A read-cleaning pipeline writes a new cleaned read and marks the old one inactive with supersededByReadId pointing forward, so the provenance chain survives.

This matters because of the delivery gate. A researcher cannot download their own sequencing files until an admin explicitly publishes them. On the order’s Sequencing Data → Overview there is a Delivery to user card with a Make downloadable to user button; it stamps Order.sequencingFilesPublishedAt. Until then, a researcher requesting the delivery gets Sequencing files are not available for this sequencing order. After publication they see only reads that are both cleaned and isActive, plus sequencing artifacts explicitly marked visibility: "customer". The button is disabled if there is nothing publishable — the API answers No cleaned reads or customer-facing reports are available to publish. Publication is reversible with Hide from user.

5. Samples are grouped into a study

A study is created by a researcher or an admin, given a title, description and (optionally) a MIxS checklist, and then has samples assigned to it. The checklist version is pinned at creation time (Study.mixsVersion) so that a later registry update never retroactively rewrites the fields of an existing study.

A study advances through two boolean flags rather than a status column: readyForSubmission (with readyAt) means the metadata is complete enough to publish, and submitted (with submittedAt and studyAccessionId) means it has been registered with ENA.

6. Pipelines run over an order or a study

Pipelines are optional. The core application — orders, samples, studies, ENA submission — works with pipelines switched off, which is the default.

Each pipeline package declares which scopes it supports, and that decides where its launch button appears:

Only a FACILITY_ADMIN can start a run; the create endpoint returns 403 for anyone else. None of the bundled packages set userCanStart, so in a default install researchers never launch anything.

A run moves pending → queued → running → completed / failed / cancelled, gets a number like MAG-20240126-001, and executes either as a local detached process or as a SLURM submission. See Running a Pipeline for the launch mechanics and Monitoring for how progress is tracked.

7. Results are published to the requesting researcher

Completing a run does not show it to the researcher who asked for the sequencing. Pipeline runs are visible to a non-admin only when both are true: they own the target study or order, and an admin has marked a run as final for that pipeline and target. The admin does this from the run’s menu with Use as final; the run then carries a Final badge, and Clear final reverses it. Exactly one run can be final per pipeline per target, so re-running MAG and marking the new run final silently replaces the old one in the researcher’s view.

Only completed runs can be marked final — otherwise the API answers Only completed pipeline runs can be selected as final.

8. The study is submitted to ENA

With ENA Webin credentials configured, the study and its samples are registered with the archive, and reads, assemblies and bins can follow. Accessions come back and are written onto the SeqDesk records: Study.studyAccessionId, Sample.sampleAccessionNumber and biosampleNumber, Read.runAccessionNumber and experimentAccessionNumber.

Note which field becomes the ENA alias: SeqDesk sends Sample.sampleId — the internal generated identifier, shaped S-<timestamp>-<random> — not the human-facing Sample Alias field. See ENA Submission for the full flow.