BioSampleTrack

A biological specimen moves through many hands and many stages before it becomes data. Without a single system of record, sample metadata, workflow position and history are easy to lose.

This project set out to model that journey explicitly: a seven-stage NGS workflow from intake and QC through sequencing, bioinformatics analysis, and completion or failure handling.

Design and build a full-stack specimen tracking system where every stage transition is an explicit, validated state change rather than a free-text status field.

Capture sample metadata at intake, prevent duplicates, and keep an audit log of everything that happens to a specimen afterwards.

Surface the state of the lab through search, filtering and dashboard analytics.

• Data layer — SQLAlchemy models over SQLite, with Pydantic schemas validating everything entering the system.
• API layer — a Python / FastAPI service exposing specimen CRUD, workflow transitions, search and analytics endpoints.
• Client layer — a React / Vite application using React Router for navigation and Recharts for dashboard analytics.
• Workflow layer — a seven-stage state machine covering intake, QC, library prep, sequencing, bioinformatics, review and completion or failure.

• Sample metadata capture, workflow state transitions, audit logging, validation, duplicate prevention, search and filtering, and dashboard analytics.
• A 21-test automated test suite covering the system.
• A GitHub Actions CI/CD pipeline running on the repository.

Results and detailed analysis available in the project repository.

• Modelling a laboratory process as explicit state transitions — rather than editable status text — is what makes validation and auditability possible.
• Validation and duplicate prevention belong at the schema boundary, where every request passes through them.
• An automated test suite wired into CI keeps a multi-stage workflow trustworthy as it grows.