hermes-team/mutascope
6
0
Fork 0
Code Issues 2 Pull requests Projects 1 Releases Packages Wiki Activity Actions
Mutation detection tool
2 commits 1 branch 0 tags 30 KiB
Find a file
Exact
Product Owner 4b9418f8c4 docs: update README with MVP spec and architecture
2026-03-13 22:03:18 +01:00
README.md docs: update README with MVP spec and architecture 2026-03-13 22:03:18 +01:00

README.md

🧬 MutaScope

Nanopore mutation detection platform — upload FASTQ reads, get nonsynonymous variant reports.

CI

What it does

  1. Upload nanopore FASTQ reads + select reference genome
  2. Pipeline automatically filters, aligns, calls variants, and annotates
  3. Report with interactive mutation table, heatmaps, and CSV/VCF export

Pipeline

FASTQ → NanoFilt → minimap2 → Clair3 → SnpEff → Report
          (filter)  (align)   (call)   (annotate)

Tools:

Step Tool Purpose
Quality filtering NanoFilt Remove low-quality reads (<Q8, <500bp)
Alignment minimap2 -ax map-ont Map reads to reference genome
Variant calling Clair3 (deep learning) SNV + indel calling, ONT-optimized
Annotation SnpEff Gene/effect annotation, nonsynonymous filter

Reference genomes: hg38 (human), hg19 (human legacy), mm10 (mouse)

Architecture

Frontend (Next.js 15) → API (FastAPI) → Redis Queue → Worker Pods (K8s)
                                                           │
                                               NanoFilt → minimap2 → Clair3 → SnpEff
                                                           │
                                                     S3 (object store)
                                                     PostgreSQL (metadata)

Stack

Layer Technology
Frontend Next.js 15 + Tailwind CSS + shadcn/ui
Backend API FastAPI + PostgreSQL + Redis
Pipeline NanoFilt, minimap2, Clair3, SnpEff
Infrastructure Kubernetes, S3-compatible storage, Docker

MVP Scope

See the Plane project board for the full backlog.

Sprint 1 — Foundation (Mar 16–29)

  • Monorepo scaffolding, CI/CD, database schema, K8s manifests
  • Pipeline tools validation spike

Sprint 2 — Core Pipeline (Mar 30 – Apr 12)

  • FASTQ upload, reference genome selection, job submission
  • Full pipeline worker: NanoFilt → minimap2 → Clair3 → SnpEff

Sprint 3 — Reports & Export (Apr 13–26)

  • Interactive mutation table with filtering/sorting
  • Heatmap visualization, CSV + VCF export
  • Job history page

Sprint 4 — Auth & Hardening (Apr 27 – May 10)

  • User accounts, data isolation, security audit
  • E2E tests, performance testing, documentation

Local Development

# Prerequisites: Docker, Docker Compose, make

git clone https://git.nixlab.pl/hermes-team/mutascope.git
cd mutascope
cp .env.example .env      # configure environment
make dev                  # start all services

# Services:
# Frontend:  http://localhost:3000
# API:       http://localhost:8000/docs
# Redis UI:  http://localhost:8001

Team

Role Agent
Product Owner po@hermes-team.local
Scrum Master sm@hermes-team.local
Architect architect@hermes-team.local
Developer dev@hermes-team.local
QA Engineer qa@hermes-team.local

Tool Citations

  • NanoFilt: De Coster et al., Bioinformatics 2018
  • minimap2: Li H., Bioinformatics 2018
  • Clair3: Zheng et al., Nature Computational Science 2022
  • SnpEff: Cingolani et al., Fly 2012

License

MIT