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
• nf-core pipelines (MAG, etc.)
• Local or SLURM execution modes
• Conda for dependency management
• Weblog + trace file monitoring

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 (with samples + reads)
  → Pipeline launcher
  → Samplesheet generation (CSV from database)
  → Nextflow command construction
  → Execution (local process or SLURM submission)
  → Monitoring (weblog events + trace parsing)
  → Output discovery (adapter scans run directory)
  → Database records (Assembly, Bin, Artifact)

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