# LIMS Seed

Next-generation sequencing (NGS) laboratory information management system. Tracks the complete workflow from sample receipt through quality control, library preparation, sequencing on high-throughput instruments, and bioinformatics analysis. Supports Illumina (NovaSeq 6000, NextSeq 2000, MiSeq) and Oxford Nanopore (MinION) platforms. Designed for a core facility processing 50-200 samples per week across multiple research groups.

## Resources

| Resource | Features |
|----------|----------|
| Project | CRUD, audit, search. Groups related samples from a single research group or grant. Tracks PI, organism, target sample count, and timeline. |
| Sample | CRUD, audit, search, export, state machine (7 states). Biological sample progressing through the NGS workflow. Carries QC metrics (concentration, volume, RIN/DIN, purity ratios) and library prep details. |
| Instrument | CRUD, audit. Sequencing instrument in the core facility. Tracks platform, serial number, operational status, maintenance schedule, and cumulative run count. |
| Protocol | CRUD, search. Standard operating procedures for library prep and sequencing. Specifies applicable sample types, platforms, input requirements, and expected turnaround. |
| Run | CRUD, audit, search, export, state machine (5 states). Sequencing run on an instrument. Processes one or more samples via the RunSamples junction table. Records post-run QC metrics (total reads, Q30, yield). |
| Analysis | CRUD, audit, state machine (4 states with retry loop). Bioinformatics analysis of sequencing run data. Runs a specific pipeline (GATK, nf-core, QIIME2, Flye) and tracks compute resources and results. |

## Relationships

| Relationship | Type | Description |
|-------------|------|-------------|
| Project hasMany Sample | hasMany | A project contains multiple samples |
| Sample belongsTo Project | belongsTo | Each sample belongs to one project |
| Instrument hasMany Run | hasMany | An instrument hosts multiple sequencing runs |
| Run belongsTo Instrument | belongsTo | Each run uses one instrument |
| Run belongsTo Protocol | belongsTo | Each run follows one protocol |
| Run belongsToMany Sample | belongsToMany | Many-to-many via RunSamples junction table |
| Run hasMany Analysis | hasMany | A run can have multiple analyses |
| Analysis belongsTo Run | belongsTo | Each analysis is for one run |

## State Machines

### Sample Workflow (7 states)

```
received --> pass_qc --> qc_passed --> begin_library_prep --> library_prep
    ^           |                                                 |
    |       fail_qc                                       begin_sequencing
    |           v                                                 v
    |       qc_failed                                         sequencing
    |           |                                                 |
    +--resubmit-+                                         begin_analysis
                                                                  v
                                                              analysis
                                                                  |
                                                              complete
                                                                  v
                                                           complete (final)
```

### Run Workflow (5 states)

```
planned --> begin_loading --> loading --> start_run --> running --> complete --> completed
                                                          |
                                                         fail
                                                          v
                                                        failed
```

### Analysis Workflow (4 states, retry loop)

```
queued --> start --> running --> complete --> completed
                       |
                      fail
                       v
                     failed --> retry --> queued (loop)
```

## Enums

| Enum | Values |
|------|--------|
| SampleType | dna (Genomic DNA), rna (Total RNA), cfDNA (Cell-free DNA), ffpe (FFPE) |
| SampleStatus | received, qc_passed, qc_failed, library_prep, sequencing, analysis, complete |
| RunStatus | planned, loading, running, completed, failed |
| InstrumentStatus | available, in_use, maintenance, offline |
| AnalysisStatus | queued, running, completed, failed |
| Organism | human (Homo sapiens), mouse (Mus musculus), rat (Rattus norvegicus), ecoli (E. coli K-12), custom |
| LibraryPrepKit | nextera_dna_flex, truseq_stranded_mrna, truseq_stranded_total_rna, twist_exome, nanopore_ligation |
| SequencingPlatform | novaseq_6000, nextseq_2000, miseq, minion |

## Roles and Permissions

| Role | Capabilities |
|------|-------------|
| admin | Full access to all resources. Can create/delete instruments and protocols. Manages users and roles. |
| pi | Principal investigator. Can create projects and submit samples. Can read all resources. |
| lab_tech | Lab technician. Can create/update samples, operate instruments, create runs, run analyses, and trigger all state machine transitions. |
| authenticated | Any authenticated user. Read-only list and read access to all resources. |

### Permission Matrix

| Resource | list | read | create | update | delete |
|----------|------|------|--------|--------|--------|
| Project | authenticated | authenticated | pi, admin | owner, pi, admin | admin |
| Sample | authenticated | authenticated | lab_tech, pi, admin | lab_tech, admin | admin |
| Instrument | authenticated | authenticated | admin | lab_tech, admin | admin |
| Protocol | authenticated | authenticated | admin | admin | admin |
| Run | authenticated | authenticated | lab_tech, admin | lab_tech, admin | admin |
| Analysis | authenticated | authenticated | lab_tech, admin | lab_tech, admin | admin |

## Seed Data

- 4 projects: BRCA WGS (human), Colorectal Organoid RNA-seq (human), Mouse Gut 16S (mouse), E. coli Assembly (ecoli)
- 8 samples: 3 BRCA tumor/normal DNA, 2 RNA-seq organoid, 1 mouse 16S, 1 E. coli, 1 FFPE
- 4 instruments: NovaSeq-1 (available), NextSeq-1 (in use), MiSeq-Bench3 (maintenance), MinION-1 (available)
- 5 protocols: WGS 30x, RNA-seq polyA, 16S V3-V4, ONT Long-Read, Whole Exome
- 4 runs: one per instrument, all in planned status
- 4 analyses: one per run, all in queued status
- 5 users: admin, dr_chen (PI), dr_patel (PI), maria (lab_tech), james (lab_tech)

## ADL Features Exercised

- Full CRUD on all 6 resources
- Relationships: belongsTo (4), hasMany (3), belongsToMany (1 via RunSamples junction)
- State machines: Sample (7-state), Run (5-state), Analysis (4-state with retry loop)
- Rich enums: 8 enums with labels, descriptions, and color codes
- Types: uuid, string, text, integer, decimal, percentage, date, datetime, email, boolean, set, url, slug
- Shared objects via $merge (Timestamp)
- Shared properties via $ref (slug)
- Audit trail on Project, Sample, Instrument, Run, Analysis
- Full-text search on Project, Sample, Protocol, Run
- Data export on Sample, Run
- Role-based permissions with 4 roles across all resources