How SeqDesk fits together
SeqDesk does three jobs — take in sequencing orders, run analysis pipelines, and submit results to the public archive — from a single app on a facility’s own server. This is a tour in four maps: the records everything hangs off, the path a job takes from a researcher’s request to a citable ENA accession, what actually happens when a pipeline runs, and every outside tool SeqDesk wires together. Each one is built from the real schema and source, and you can drag, zoom and click every node.
Start with the records
Before any of the moving parts make sense, it helps to see the few records everything else hangs off. In SeqDesk an Order is the unit of intake; it holds Samples; each sample holds its sequencing data as Reads; and a Study groups samples together for analysis and submission. One detail surprises people: a study links to its samples by an optional foreign key, not a many-to-many join — so a sample belongs to at most one study at a time.
The data model
Everything in SeqDesk hangs off four records: an Order holds Samples, each Sample holds its FASTQ as Reads, and a Study groups Samples for analysis and submission. A pipeline run then hangs assemblies and bins off the same samples. Drag a card or click it for detail.
Each card is a database table. Click one to see what it stores and which ENA accession columns it carries. Solid arrows are required relations; dashed are optional.
The gold cards — PipelineRun, Assembly, Bin — are what analysis adds later. Every assembly and bin is stamped with the run that produced it, so a result can always be traced back to its inputs. We’ll see those get created in the third map.
The path a job takes
Those records get filled in by two kinds of people. A researcher sets up the order and its samples; a facility admin does the lab and compute work and the archive submission. The handoff happens when the researcher submits — after that the sample data is read-only and the facility takes over. ENA, at the end, is the only step that leaves the building.
From order to archive
A single job from a researcher's request to a public ENA record. The researcher sets up the order; the facility admin does the lab and compute work; ENA mints the accessions that come back. Click any step to see who does it and what it touches.
Follow the arrows. Researcher steps (green) set up the order; the facility admin (gold) assigns data, runs analysis, and submits; ENA returns accessions the researcher can then cite.
An order's three states
The order itself carries a small status of its own. It is a plain text column (default DRAFT), not a fixed enum — these are the states the app actually drives.
The two ENA steps are deliberately separate: first the study and samples are registered as metadata, then the actual sequence files go up. That second step is a whole story on its own — we pull it apart in “Up the wire”, down to the single YAML file SeqDesk hands to submg.
What “launch pipeline” actually does
“Launch pipeline” is one click in the previous map, but a lot happens behind it. A pipeline in SeqDesk isn’t custom code — it’s a folder of declarative files that describe how to build the input, what command to run, and how to read the output. SeqDesk does the same six steps for every pipeline: turn the study’s samples into a samplesheet, build the Nextflow command, run it, watch it, find the outputs, and write them back as records.
Inside a pipeline run
A pipeline in SeqDesk is a folder of declarative files, not custom code. At launch SeqDesk turns a study's samples into a samplesheet, builds a Nextflow command, runs it (locally or on SLURM), watches it, then parses the outputs back into database rows. Click a card for the file or function behind it.
Read left to right: a package plus the study's data go in, SeqDesk's six steps build and watch the run, Nextflow does the work, and the results come back as Assembly, Bin, report and Read records.
A run's status, start to finish
Every pipeline run moves through the same status line. Local runs skip the queue; the three terminal states are the only ways a run ends.
The same machinery runs a quick FastQC check or a full metagenome assembly — only the package changes. There’s a longer walk-through of this in “How pipelines run inside SeqDesk” and in the architecture docs.
Everything it talks to
Step back far enough and SeqDesk is a hub. It’s one self-hosted app, but to do its three jobs it orchestrates a handful of outside tools — a database, a workflow engine, an optional cluster, a sequencer’s output, and the archive. Crucially, none of these are in someone else’s cloud: every spoke runs on the facility’s own infrastructure, and the only link that leaves the network is the one to ENA.
The ecosystem
SeqDesk is one self-hosted app, but it orchestrates a handful of outside tools. Here is every system it talks to and what flows across each link. Arrows point in the direction SeqDesk initiates; dashed links are optional, admin-only integrations. Click a node for the mechanism.
SeqDesk sits at the center. It persists to PostgreSQL and gates users with NextAuth, drives Nextflow (optionally via SLURM) for analysis, ingests live ONT reads through the stream-monitor, and archives to ENA through its own XML path and the submg → Webin-CLI chain.
The dashed spokes — SLURM and live MinKNOW ingest — are optional: a small facility can run SeqDesk with neither, executing pipelines locally and assigning files by scanning a folder. The archive path is the busiest corner: SeqDesk registers metadata to ENA itself, but hands the heavy file uploads to submg, which drives ENA’s Webin-CLI.
Data & method. Every node and edge is transcribed from real source. The data model comes from SeqDesk’s Prisma schema (prisma/schema.prisma: Order, Study, Sample, Read, PipelineRun, Assembly, Bin); the pipeline internals from src/lib/pipelines (generic-executor, pipeline-run-service, generic-adapter, monitor-status, output-resolver) and the monitoring docs; the ecosystem from the ENA client, the submg runner, and the architecture docs. A few things are simplified for legibility: the data-model map leaves out the per-order checklist container and the sequencing-run↔sample barcode join; the pipeline map folds Nextflow’s weblog and trace.txt channels into one “Monitor” node, and the submg path uses a dedicated runner rather than the generic discover/parse path shown. The order status is a free-text column (default DRAFT), not a fixed enum — the three states shown are the ones the app drives. The INSDC link (ENA / DDBJ / NCBI sharing accessions) is archive domain context, not a SeqDesk integration: SeqDesk only talks to ENA directly. submg is the open-source tool by Tubbesing et al. (BioData Mining, 2025).