BioFlowValidator

A transparent, rule-based validator for RNA-seq differential expression analysis workflows.

BioFlowValidator catches common scientific and computational errors in RNA-seq data before expensive analysis begins — acting as a pre-analysis guard rail for wet-lab biologists, students, and clinical researchers.

Features

• ✅ 32 validation rules across 5 categories (format, sample, gene ID, normalization, biology)
• 🔬 Detects: sample mismatches, mixed gene ID namespaces, pre-normalized counts, too few replicates, library size outliers, and more
• 📊 Human-readable HTML report + machine-readable JSON
• 🚀 REST API (FastAPI) + React/TypeScript frontend
• 🐳 Single-command Docker startup

Quick Start

Docker (recommended)

git clone https://github.com/Rashidmstar12/BioFlowValidator.git
cd BioFlowValidator
docker compose up --build

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

Local Development

Backend:

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

Frontend:

cd frontend
npm install
npm run dev

Open http://localhost:5173.

Inputs

Validation Rule Categories

See docs/validation_rules.md for the full rule reference.

Running Tests

cd backend
python -m pytest tests/ -v

Run the dataset benchmark:

python datasets/benchmark.py

API Reference

See docs/api_spec.md or browse the interactive docs at http://localhost:8000/docs.

Repository Structure

BioFlowValidator/
├── backend/           # Python FastAPI application
│   ├── app/
│   │   ├── engine/    # FileParser, RuleRegistry, RuleRunner
│   │   ├── models/    # RuleResult, ValidationReport, ValidationContext
│   │   ├── rules/     # format/, sample/, gene/, normalization/, biology/
│   │   ├── report/    # JSONExporter, HTMLExporter
│   │   └── routers/   # FastAPI route handlers
│   └── tests/         # Unit + integration tests
├── frontend/          # React + TypeScript + Vite SPA
├── datasets/          # Valid + faulty example datasets + benchmark
├── docs/              # API spec, validation rules reference
├── Dockerfile.backend
├── Dockerfile.frontend
└── docker-compose.yml

Design Principles

• Validation only — no analysis, no statistical computation
• Transparent — every rule has a documented ID, description, and suggestion
• Auditable — JSON report includes file SHA-256 hash and timestamp
• Scientifically conservative — ambiguous cases produce WARNING not ERROR
• Reproducible — same inputs always produce identical outputs

License

MIT