Architecture

SeqDesk is a full-stack web application built with modern JavaScript/TypeScript tools and designed for self-hosted deployment.

Tech Stack

Application Layers

Frontend

• Next.js App Router with React Server Components
• Client-side state management with React hooks
• Interactive data tables for sample editing
• Real-time pipeline monitoring via polling

API Layer

• Next.js Route Handlers (/api/*)
• REST API endpoints for all operations
• Role-based access control (RESEARCHER, FACILITY_ADMIN)
• JSON request/response format

Data Layer

• Prisma ORM for database access
• PostgreSQL for development, self-hosted production, and Vercel deployments
• JSON fields for flexible metadata storage (checklistData, customFields, etc.)

Pipeline Execution

• Nextflow for workflow orchestration
• packaged study and order pipelines
• Local or SLURM execution modes
• Conda for dependency management
• Weblog + trace file monitoring

Pipeline Package Contract

SeqDesk packages workflows behind a manifest-first contract:

• manifest.json defines runtime scope, execution, inputs, outputs, and safe writeback
• registry.json defines presentation metadata and editable config schema
• samplesheet.yaml defines generated inputs
• optional discovery scripts resolve produced files back to SeqDesk records

This allows study pipelines and order pipelines to share the same package format while still exposing different runtime capabilities.

Configuration Resolution

The multi-source configuration system resolves settings in this order:

1. Environment variables (SEQDESK_*)  ← highest priority
2. Config file (seqdesk.config.json)
3. Database settings (SiteSettings)
4. Built-in defaults                  ← lowest priority

Configuration is loaded at startup, cached for 60 seconds, and tracks the source of each resolved value.

Pipeline Execution Flow

Study or Order context
  → Package resolution (manifest + registry)
  → Pipeline launcher
  → Generated package input (samplesheet or manifests from database)
  → Nextflow command construction
  → Execution (local process or SLURM submission)
  → Monitoring (weblog events + trace parsing)
  → Output discovery (artifact scan + optional discovery script)
  → Database records / validated writeback (Assembly, Bin, Artifact, Read fields)

ENA Submission Flow

Study + Samples (validated)
  → XML generation (Study, Sample, Submission XMLs)
  → HTTP POST to ENA API (Basic Auth)
  → Receipt XML parsing
  → Accession number storage

File System Layout

seqdesk/
├── src/
│   ├── app/          # Next.js pages and API routes
│   ├── lib/          # Shared libraries
│   │   ├── config/   # Configuration system
│   │   ├── pipelines/# Pipeline execution
│   │   ├── ena/      # ENA submission
│   │   └── files/    # File discovery and matching
│   └── types/        # TypeScript type definitions
├── prisma/
│   └── schema.prisma # Database schema
├── pipelines/        # Pipeline packages (MAG, etc.)
├── data/             # Default data (sequencing tech, etc.)
├── public/           # Static assets
└── seqdesk.config.json  # Configuration file

Security

• Password hashing: bcrypt
• Session management: JWT tokens via NextAuth.js
• Role-based access: middleware checks on API routes
• File access: restricted to configured base path, path traversal blocked
• ENA credentials: encrypted in database, masked in API responses
• Configuration secrets: recommended to use environment variables