Microbiome Runner

CesurAkcay

Desktop app for running and monitoring Snakemake-based microbiome analysis pipelines. Tauri 2 + Svelte 5 + Rust.

MicrobiomeRunner

Desktop application for running and monitoring Snakemake-based microbiome analysis pipelines. Configure samples, launch runs, track progress in real time, and view generated reports — all from a single interface.

Built with Tauri 2 (Rust) + Svelte 5 + TailwindCSS 4 + Vite 8.

Features

Pipeline Management — Configure and launch Snakemake microbiome analysis runs with per-sample tracking
Real-time Monitoring — Live progress bars, rule-level status updates, and streaming log output
Dual Execution Backends — Run pipelines via Conda environments or Docker containers
Run History — Browse, filter, and inspect past runs with full metadata and result persistence
Report Viewing — View generated PDF and Excel reports directly in the app
System Observability — Real-time system metrics (CPU, memory), pipeline logs, and application logs
Internationalization — English and Turkish language support
Dark / Light Theme — Toggle between themes with system preference detection
Cross-platform — Linux (.deb, .AppImage, .rpm), macOS (.dmg), and Windows (.exe NSIS installer)

Tech Stack

Layer	Technology
Frontend	Svelte 5, TailwindCSS 4, shadcn-svelte, Lucide icons
Backend	Rust (2024 edition), Tauri 2
Bundler	Vite 8
Package Manager	Bun
Pipeline Engine	Snakemake (external)
CI/CD	GitHub Actions

Prerequisites

Bun (package manager)
Rust (stable toolchain)
Tauri 2 system dependencies:
- Linux (Debian/Ubuntu):
```
sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file \
  libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev patchelf
```
- macOS: Xcode Command Line Tools (xcode-select --install)
- Windows: WebView2 (bundled automatically via NSIS installer)

Important Notes for Contributors

Docker image not included

The bundled Docker image (microbiome-runner.tar.gz) is not included in this repository. To use the Docker execution backend you must supply your own Snakemake-based microbiome analysis image and configure its path in the app's Settings screen. Alternatively, use the Conda backend, which requires only a Conda/Mamba installation and a Snakemake environment.

The app ships with a simple login gate. Default credentials for local development:

Username	Password
`admin`	`admin123`

This is purely a local UI gate and does not connect to any remote authentication service.

Setup

# Clone the repository
git clone https://github.com/CesurAkcay/microbiome-runner.git
cd microbiome-runner

# One-command bootstrap (checks prerequisites + installs deps)
./setup.sh

Or manually:

bun install

Development

# Full Tauri dev (frontend + Rust hot-reload)
bun run dev

# Frontend only (Vite on port 5173)
bun run dev:frontend

# Svelte type checking
bun run check

Testing

# Run frontend tests (vitest)
bun run test

# Run frontend tests in watch mode
bun run test:watch

# Run Rust tests (cargo-nextest)
bun run test:rust

# Run all coverage (Rust + frontend)
bun run test:coverage

# Rust coverage only (outputs lcov.info)
bun run test:coverage:rust

# Frontend coverage only
bun run test:coverage:frontend

Architecture

Overview

The app follows a clear frontend/backend split. The Rust backend handles pipeline execution, file I/O, and system operations. The Svelte frontend manages all UI and state. They communicate through two mechanisms:

Commands — Frontend calls backend via invoke() from @tauri-apps/api/core (27 commands: pipeline control, history, settings, environment checks, filesystem utilities, export)
Events — Backend pushes real-time updates via app.emit("pipeline-event", event), frontend listens with listen() from @tauri-apps/api/event

Event Types (Backend to Frontend)

RuleStarted, RuleCompleted, RuleFailed, Progress, LogLine, RunCompleted, RunStopped, SampleStarted, SampleCompleted, SampleResult, SystemMetrics

Project Structure

microbiome-runner/
├── src/                          # Frontend (Svelte 5)
│   ├── App.svelte                # Root component (auth gate + shell)
│   └── lib/
│       ├── components/
│       │   ├── shell/            # Layout: AppShell, Sidebar, HeaderBar, ThemeToggle
│       │   ├── views/            # Main views (Home, Launch, RunDetail, History, Settings, Observability, Help, Login)
│       │   ├── pipeline/         # Pipeline UI (progress, controls, sample cards)
│       │   ├── history/          # History cards, rerun dialog
│       │   ├── reports/          # PDF and Excel viewers
│       │   └── ui/               # shadcn-svelte primitives
│       ├── state/                # Svelte 5 rune-based state singletons
│       │   ├── runs.svelte.ts    # Run lifecycle, event handling
│       │   ├── ui.svelte.ts      # View navigation
│       │   ├── config.svelte.ts  # Pipeline config + validation
│       │   ├── settings.svelte.ts # App settings (theme, paths, backend)
│       │   ├── samples.svelte.ts # Sample form state
│       │   ├── reports.svelte.ts # Report handling
│       │   └── auth.svelte.ts    # Authentication + roles
│       ├── i18n/                 # Internationalization (en, tr)
│       └── types/                # TypeScript type definitions
├── src-tauri/                    # Backend (Rust)
│   └── src/
│       ├── lib.rs                # Tauri command handlers, app builder
│       └── pipeline/
│           ├── runner.rs         # Pipeline execution engine
│           ├── state.rs          # Pipeline state (stop signals, PIDs)
│           ├── types.rs          # Event enums, configs, records
│           ├── history.rs        # Run record persistence (JSON)
│           ├── parser.rs         # Snakemake output parser
│           ├── conda.rs          # Conda backend
│           ├── docker.rs         # Docker backend
│           ├── preflight.rs      # Environment checks
│           ├── settings.rs       # Settings serialization
│           ├── logging.rs        # Structured logging (tracing)
│           ├── util.rs           # Shared pipeline utilities
│           └── mod.rs            # Module declarations
├── .github/workflows/build.yml   # CI/CD pipeline
└── build-all.sh                  # Cross-platform build script

Component Hierarchy

App.svelte
├── LoginView (when not authenticated)
└── AppShell (when authenticated)
    ├── AppSidebar (navigation + run list + NewRunDialog)
    ├── HeaderBar (title, global progress, run controls, theme/language toggle)
    └── ViewContainer (dynamic view switching)
        ├── HomeView
        ├── LaunchView (configure & launch runs)
        ├── RunDetailView (progress, controls, batch overview, sample results, logs)
        ├── HistoryView (past runs with filtering/selection)
        ├── SettingsView (conda/docker paths, defaults, UI settings)
        ├── ObservabilityView (metrics, pipeline logs, app logs)
        └── HelpView (usage guide)

State Management

State is managed via class-based singletons using Svelte 5 runes ($state, $derived, $derived.by()). Each state module exports a single instance (e.g., runsState, authState, settingsState).

Data Persistence

Run records are stored as individual JSON files (UUID-named) in the OS-specific config directory. App settings are persisted as app_settings.json in the same directory.

Internationalization

The app supports two languages, switchable from the header bar:

English (en)
Turkish (tr)

Translations are stored in src/lib/i18n/translations/ with typed keys via TranslationKey.

Code Quality

Pre-commit Hooks (Automatic)

Every git commit triggers automatic checks via Husky + lint-staged:

ESLint — lints TypeScript/Svelte files, auto-fixes what it can
Prettier — auto-formats code (indentation, quotes, spacing, Tailwind class order)
cargo fmt — checks Rust formatting
Clippy — Rust linter for common mistakes

If any check fails, the commit is blocked.

Manual Commands

# Run all checks
bun run quality

# Auto-fix all issues
bun run quality:fix

# Individual commands
bun run lint           # ESLint check
bun run lint:fix       # ESLint auto-fix
bun run format         # Prettier format
bun run format:check   # Prettier check (no changes)
bun run check          # Svelte type checking
bun run lint:rust      # Rust fmt + clippy
bun run clippy         # Rust clippy only
bun run fmt            # Rust format only

Build

# Full production build (auto-detects platform)
bun run build

# Frontend only
bun run build:frontend

# Linux build (.deb)
./build-all.sh

# Windows build (run on a Windows machine)
powershell -ExecutionPolicy Bypass -File build-windows.ps1

Build Outputs

Platform	Formats	Location
Linux	`.deb`, `.AppImage`, `.rpm`	`src-tauri/target/release/bundle/deb/`
macOS	`.dmg`, `.app`	`src-tauri/target/aarch64-apple-darwin/release/bundle/dmg/`
Windows	`.exe` (NSIS installer)	`src-tauri/target/release/bundle/nsis/`

Deploy

Install the built packages on target machines:

Linux (Debian/Ubuntu): sudo dpkg -i microbiome-runner_0.1.0_amd64.deb
Linux (RPM): sudo rpm -i microbiome-runner-0.1.0.x86_64.rpm
Linux (AppImage): chmod +x MicrobiomeRunner-App_0.1.0.AppImage && ./MicrobiomeRunner-App_0.1.0.AppImage
macOS: Open the .dmg and drag to Applications
Windows: Run the MicrobiomeRunner_0.2.0_x64-setup.exe installer

macOS Installation

Download MicrobiomeRunner_x.x.x_aarch64.dmg from the latest release
Open the .dmg and drag MicrobiomeRunner to Applications
On first launch, macOS may warn about an unidentified developer:
- Right-click the app in Applications > Open > Open in the dialog
- This only needs to be done once

Requirements:

macOS 11.0 (Big Sur) or later
Apple Silicon (M1/M2/M3/M4) or Intel Mac with Rosetta 2
Docker Desktop for Mac

Docker auto-start: When running a pipeline with the Docker backend, the app automatically launches Docker Desktop if it is not running.

Windows Installation

The NSIS installer handles everything automatically:

No admin rights required — installs to %LOCALAPPDATA%\MicrobiomeRunner\
WebView2 — downloaded and installed silently if not already present
Docker image — if bundled in the installer and Docker Desktop is running, the image is auto-loaded during installation
Start Menu shortcut — created automatically