docs: update README with MVP spec and architecture

2026-03-13 22:03:18 +01:00 · 2026-03-13 22:03:18 +01:00 · 4b9418f8c4
commit 4b9418f8c4
parent 11828a2138
1 changed files with 115 additions and 2 deletions
--- a/README.md
+++ b/README.md
@ -1,3 +1,116 @@
-# mutascope
+# 🧬 MutaScope

-Mutation detection tool
+**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