# 🧬 MutaScope

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

[![CI](https://git.nixlab.pl/hermes-team/mutascope/badges/main/pipeline.svg)](https://git.nixlab.pl/hermes-team/mutascope/pipelines)

---

## 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](https://plane.nixlab.pl) 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

```bash
# 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