Helical Workbench

A Next.js workbench for running and comparing model jobs on single-cell datasets. It combines a jobs queue, job status modal, and rich results views with metrics, KPIs, and confusion matrices.

Quick start

Frontend:

npm install
npm run dev

Open http://localhost:3000 in your browser.

Backend (mock API):

python -m venv .venv
source .venv/bin/activate
pip install -r backend/requirements.txt
cd backend
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Optional: set NEXT_PUBLIC_API_BASE if the API runs elsewhere.

Tests

npm run test

Quick overview: Right now the test suite is intentionally minimal and runs a single Jest test.

If I were to add more, I would focus on:

• Core flows: create job → list → detail → delete, including error states.
• Settings persistence: localStorage hydration and toggles.
• Chart rendering: KPIs and compare mode with real fixture data.
• API layer: request helper error parsing and delete behavior.

Login

The sign-in form is UI-only and accepts any credentials.

Features

• Jobs list with status, progress bars, ETA, and queue ordering controls
• Job status modal for queued/running/failed jobs with logs and retry actions
• Job creator modal with dataset selection (sample or upload) and model parameters
• Job detail views with charts, regression and classification metrics, KPIs, and confusion matrices
• Compare mode to view an alternate model side by side
• Duplicate job action to rerun with the same dataset (and model)
• Settings for workbench name/summary, dark mode, and vivid colour theme

Data assumptions and notes

• The backend is a mock API that simulates job progress and outputs.
• Job outputs for charts are static JSON fixtures in src/data.
• Sample datasets include a long-running 10gb_dataset.h5ad and a deterministic failure case.
• Uploads accept .h5ad only and are represented as metadata in the job payload.
• Queue ordering is managed client-side and is not persisted server-side.

API/schema considerations

• API base defaults to http://localhost:8000 and exposes GET /jobs, POST /jobs, GET /jobs/{id}, and DELETE /jobs/{id}.
• Job payloads include datasetRef, model type, and run parameters (seed, batchSize, maxCells, output).
• The backend emits a runFingerprint and task-level logs for the status modal.
• There is no auth layer in the mock API.

UI/UX decisions

• The UI is not responsive and is intended for desktop-only prototyping, tested in Google Chrome 144.0.7559.97 (Official Build) (arm64).
• Tailwind CSS v4 with tokens defined in app/globals.css via @theme.
• Chart rendering uses react-chartjs-2 and Chart.js for KPIs and scatter plots.
• Dialogs are built with Radix UI for consistent modal behaviour.
• Client components use "use client"; where hooks, local state, or browser APIs (e.g., localStorage) are required, keeping server and client responsibilities explicit.
• Dark mode is class-based (.dark) and a vivid mode overrides accent tokens (.vivid).
• ETA is computed client-side from progress and start time for running jobs.
• Compare mode is toggled in the job detail header and reuses layout for side-by-side results.

Code quality and maintainability

• React Query handles data fetching and polling for job status.
• Types are centralised in src/lib/types.ts and shared across components.
• UI is split into focused components (JobsList, JobListItem, JobStatus, JobCreator).
• Mock data and API responses are isolated to keep UI work predictable.

Error handling

• Loading and error states are shown for job lists and job detail pages.
• Job creation errors surface inline in the Job Creator modal.
• Failed jobs show guidance and error logs in the status modal.

AI usage

• AI assistance was used for copy editing and troubleshooting; changes were reviewed and adjusted manually. GitHub copilot was used with auto suggestions.

Commit message guide

Follow a lightweight conventional format:

<type>: <short summary>

Optional body with context or rationale

Recommended types: feat, fix, refactor, test, docs, chore.

Brand guidelines

• Tokens live in app/globals.css under @theme and are overridden by .dark and .vivid.
• Base colours: brand black, grey, light grey, white, error.
• Accent palette: blue, lime, cyan, purple, violet, teal, indigo.
• Light theme: text uses brand black, background uses brand light grey, surface uses brand white.
• Dark theme: text uses brand white, background uses a dark oklch tone, surface uses brand black.
• Radius: --radius-brand is 4px.
• components/BrandStyleGuide.tsx is included to visualise the token system and make colour decisions concrete during development.