From 4b9418f8c42fcc6907932c9d5db46c395a83cb5d Mon Sep 17 00:00:00 2001
From: Product Owner <po@nixlab.pl>
Date: Fri, 13 Mar 2026 22:03:18 +0100
Subject: [PATCH] docs: update README with MVP spec and architecture

---
 README.md | 117 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 115 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index b0d1a1b..c898199 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,116 @@
-# mutascope
+# 🧬 MutaScope
 
-Mutation detection tool
\ No newline at end of file
+**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