gws_core

Lab Flow Management Application: Comprehensive Requirements Document

1. Overview

• This document outlines the functional and technical requirements for a Lab Flow Management Application.
• The application will support: Item sheet managementBatch creation and trackingQuality procedures (QP)Transformation tracking
• Item sheet management
• Batch creation and tracking
• Quality procedures (QP)
• Transformation tracking
• Goals: Ensure compliance and traceability.Provide user-friendly workflows for lab teams.
• Ensure compliance and traceability.
• Provide user-friendly workflows for lab teams.

3. Core Modules and User Stories

A. Item Sheet Management

Goal:Centralize and standardize documentation for all lab items (consumables and non-consumables).

User Stories:

• As a Quality Team member, I want to Create and edit item sheets so that all lab items are documented with technical details and compliance information. Fields for Non-Consumables (Instruments/Kits):Name (required)FilesTags (e.g., "Hazardous", "Priority")NoteFields for Consumables (Reagents):Name (required)Unit (mL, g, etc.) (required)Quantity (required, e.g., "10 mL")FilesStorage Conditions (e.g., "-20°C", "Room Temperature"Tags (e.g., "Hazardous", "Priority")Note
• Create and edit item sheets so that all lab items are documented with technical details and compliance information. Fields for Non-Consumables (Instruments/Kits):Name (required)FilesTags (e.g., "Hazardous", "Priority")NoteFields for Consumables (Reagents):Name (required)Unit (mL, g, etc.) (required)Quantity (required, e.g., "10 mL")FilesStorage Conditions (e.g., "-20°C", "Room Temperature"Tags (e.g., "Hazardous", "Priority")Note
• Fields for Non-Consumables (Instruments/Kits):Name (required)FilesTags (e.g., "Hazardous", "Priority")Note
• Name (required)
• Files
• Tags (e.g., "Hazardous", "Priority")
• Note
• Fields for Consumables (Reagents):Name (required)Unit (mL, g, etc.) (required)Quantity (required, e.g., "10 mL")FilesStorage Conditions (e.g., "-20°C", "Room Temperature"Tags (e.g., "Hazardous", "Priority")Note
• Name (required)
• Unit (mL, g, etc.) (required)
• Quantity (required, e.g., "10 mL")
• Files
• Storage Conditions (e.g., "-20°C", "Room Temperature"
• Tags (e.g., "Hazardous", "Priority")
• Note
• As a Lab Technician, I want to: Search and filter item sheets by name, supplier, type, or tags so I can quickly find and select items for batch creation.
• Search and filter item sheets by name, supplier, type, or tags so I can quickly find and select items for batch creation.
• As a Quality Team member, I want to: Add or remove tags from item sheets to categorize and organize items effectively.
• Add or remove tags from item sheets to categorize and organize items effectively.

B. Inventory Management

Goal:Track batches (internal or received) with full traceability, supporting multiple items per batch.

User Stories:

• As a Lab Technician, I want to: Declare a reception (internal or received) so I can manage stock efficiently. Reception Workflow:Click "Receive" button.Fill in metadata: External Lot Number (mandatory, e.g., supplier’s lot ID)stored in tagInternal Lot Number (auto-generated or manual)stored in tagCreation Date (auto-filled)Supplier (required) Add one or more items from the Item Sheet: Search and select items (consumables or non-consumables).Create a new item if that does not existFor each item, specify: Quantity (unity)Expiration Date (optional for non-consumables, required for consumables)Location (required)Barcode (auto-generated or scanned)Custom Label (optional)Tags (e.g., "Hazardous", "Priority") => hérité Notes (free text)Attachments (e.g., Certificate of Analysis)Serial Number (optional) -> non consumable. 1 serial number = 1 item unitSave Batch: System validates inputs and creates the batch with all associated items.Key Rules:A batch can contain multiple items (e.g., a kit with reagents, buffers, and instruments).Each item in the batch must have its own quantity and expiry date (if applicable).The system auto-calculates the total batch quantity based on item quantities.
• Declare a reception (internal or received) so I can manage stock efficiently. Reception Workflow:Click "Receive" button.Fill in metadata: External Lot Number (mandatory, e.g., supplier’s lot ID)stored in tagInternal Lot Number (auto-generated or manual)stored in tagCreation Date (auto-filled)Supplier (required) Add one or more items from the Item Sheet: Search and select items (consumables or non-consumables).Create a new item if that does not existFor each item, specify: Quantity (unity)Expiration Date (optional for non-consumables, required for consumables)Location (required)Barcode (auto-generated or scanned)Custom Label (optional)Tags (e.g., "Hazardous", "Priority") => hérité Notes (free text)Attachments (e.g., Certificate of Analysis)Serial Number (optional) -> non consumable. 1 serial number = 1 item unitSave Batch: System validates inputs and creates the batch with all associated items.Key Rules:A batch can contain multiple items (e.g., a kit with reagents, buffers, and instruments).Each item in the batch must have its own quantity and expiry date (if applicable).The system auto-calculates the total batch quantity based on item quantities.
• Reception Workflow:Click "Receive" button.Fill in metadata: External Lot Number (mandatory, e.g., supplier’s lot ID)stored in tagInternal Lot Number (auto-generated or manual)stored in tagCreation Date (auto-filled)Supplier (required) Add one or more items from the Item Sheet: Search and select items (consumables or non-consumables).Create a new item if that does not existFor each item, specify: Quantity (unity)Expiration Date (optional for non-consumables, required for consumables)Location (required)Barcode (auto-generated or scanned)Custom Label (optional)Tags (e.g., "Hazardous", "Priority") => hérité Notes (free text)Attachments (e.g., Certificate of Analysis)Serial Number (optional) -> non consumable. 1 serial number = 1 item unitSave Batch: System validates inputs and creates the batch with all associated items.
• Click "Receive" button.
• Fill in metadata: External Lot Number (mandatory, e.g., supplier’s lot ID)stored in tagInternal Lot Number (auto-generated or manual)stored in tagCreation Date (auto-filled)Supplier (required)
• External Lot Number (mandatory, e.g., supplier’s lot ID)stored in tag
• stored in tag
• Internal Lot Number (auto-generated or manual)stored in tag
• stored in tag
• Creation Date (auto-filled)
• Supplier (required)
• Add one or more items from the Item Sheet: Search and select items (consumables or non-consumables).Create a new item if that does not existFor each item, specify: Quantity (unity)Expiration Date (optional for non-consumables, required for consumables)Location (required)Barcode (auto-generated or scanned)Custom Label (optional)Tags (e.g., "Hazardous", "Priority") => hérité Notes (free text)Attachments (e.g., Certificate of Analysis)Serial Number (optional) -> non consumable. 1 serial number = 1 item unit
• Search and select items (consumables or non-consumables).
• Create a new item if that does not exist
• For each item, specify: Quantity (unity)Expiration Date (optional for non-consumables, required for consumables)Location (required)Barcode (auto-generated or scanned)Custom Label (optional)Tags (e.g., "Hazardous", "Priority") => hérité Notes (free text)Attachments (e.g., Certificate of Analysis)Serial Number (optional) -> non consumable. 1 serial number = 1 item unit
• Quantity (unity)
• Expiration Date (optional for non-consumables, required for consumables)
• Location (required)
• Barcode (auto-generated or scanned)
• Custom Label (optional)
• Tags (e.g., "Hazardous", "Priority") => hérité
• Notes (free text)
• Attachments (e.g., Certificate of Analysis)
• Serial Number (optional) -> non consumable. 1 serial number = 1 item unit
• Save Batch: System validates inputs and creates the batch with all associated items.
• Key Rules:A batch can contain multiple items (e.g., a kit with reagents, buffers, and instruments).Each item in the batch must have its own quantity and expiry date (if applicable).The system auto-calculates the total batch quantity based on item quantities.
• A batch can contain multiple items (e.g., a kit with reagents, buffers, and instruments).
• Each item in the batch must have its own quantity and expiry date (if applicable).
• The system auto-calculates the total batch quantity based on item quantities.

 Ou alors 1 lot externe peut contenir des items différents ? Oui Et pour le lot interne ? Oui Le barcode est vraiment nécéssaire ( a voir) ?On met vraiment le N° de serie obligatoire ?

• As an Inventory Manager, I want to: Edit batch details (e.g., update item quantities, locations, or tags) to correct errors or reflect changes.
• Edit batch details (e.g., update item quantities, locations, or tags) to correct errors or reflect changes.

Ca veut dire quoi? On modifie la récéption ?

• As a Lab Technician, I want to: Perform actions on batches (e.g., transformations, splits, moves) to manage lab workflows effectively. Supported Actions:Receive (log new stock)Move (change location of an item)Relabel (update labels)Retag (update tags)Discard (remove expired/contaminated batches)TransformConsume (reduce quantity of a specific item)Split (divide a batch into sub-items)Combine (merge multiple batches)Dilute/Concentrate (adjust sample properties)
• Perform actions on batches (e.g., transformations, splits, moves) to manage lab workflows effectively. Supported Actions:Receive (log new stock)Move (change location of an item)Relabel (update labels)Retag (update tags)Discard (remove expired/contaminated batches)TransformConsume (reduce quantity of a specific item)Split (divide a batch into sub-items)Combine (merge multiple batches)Dilute/Concentrate (adjust sample properties)
• Supported Actions:Receive (log new stock)Move (change location of an item)Relabel (update labels)Retag (update tags)Discard (remove expired/contaminated batches)TransformConsume (reduce quantity of a specific item)Split (divide a batch into sub-items)Combine (merge multiple batches)Dilute/Concentrate (adjust sample properties)
• Receive (log new stock)
• Move (change location of an item)
• Relabel (update labels)
• Retag (update tags)
• Discard (remove expired/contaminated batches)
• TransformConsume (reduce quantity of a specific item)Split (divide a batch into sub-items)Combine (merge multiple batches)Dilute/Concentrate (adjust sample properties)
• Consume (reduce quantity of a specific item)
• Split (divide a batch into sub-items)
• Combine (merge multiple batches)
• Dilute/Concentrate (adjust sample properties)
• As a Lab Technician, I want to: Scan barcodes to quickly retrieve batch or item information (optional).
• Scan barcodes to quickly retrieve batch or item information (optional).

Trop compliqué pour une v1. Ou alors il faut que les gens ai des tablette. 

C. Instrument Compliance

Goal:Ensure instruments are qualified, calibrated, and audit-ready.

User Stories:

• As a Quality Team member, I want to: Track instrument qualification status to ensure compliance with lab standards. Qualification Status:Planned (qualification pending)In Progress (tests/docs in progress)Qualified (approved for use) => Until the Expiration dateNot Qualified (failed or never qualified)Upload qualification records (IQ/OQ/PQ) to provide evidence for audits. Fields for Each Record:Type: IQ (Installation Qualification) OQ (Operational Qualification)PQ (Performance Qualification)DateOperator (who performed the qualification)Result (Pass/Fail + summary)Attachment (PDF report)Monitor calibration status to schedule recalibration and ensure instrument accuracy. Calibration Status:The user must be able to enter the date of the next calibration. Based on this date, a color code (green, orange, or red) will highlight this section to indicate whether the date is far away, approaching, or expired.An alert system will also be put in place to notify the person responsible when the expiration date is approaching. To receive this notification, they will need to configure the system by specifying the alert date and the person or persons who should receive it.Fields:Certificate (PDF upload)Expiry DateReceive notifications for upcoming calibration or qualification renewals (see configuration system section)
• Track instrument qualification status to ensure compliance with lab standards. Qualification Status:Planned (qualification pending)In Progress (tests/docs in progress)Qualified (approved for use) => Until the Expiration dateNot Qualified (failed or never qualified)
• Qualification Status:Planned (qualification pending)In Progress (tests/docs in progress)Qualified (approved for use) => Until the Expiration dateNot Qualified (failed or never qualified)
• Planned (qualification pending)
• In Progress (tests/docs in progress)
• Qualified (approved for use) => Until the Expiration date
• Not Qualified (failed or never qualified)
• Upload qualification records (IQ/OQ/PQ) to provide evidence for audits. Fields for Each Record:Type: IQ (Installation Qualification) OQ (Operational Qualification)PQ (Performance Qualification)DateOperator (who performed the qualification)Result (Pass/Fail + summary)Attachment (PDF report)
• Fields for Each Record:Type: IQ (Installation Qualification) OQ (Operational Qualification)PQ (Performance Qualification)DateOperator (who performed the qualification)Result (Pass/Fail + summary)Attachment (PDF report)
• Type: IQ (Installation Qualification) OQ (Operational Qualification)PQ (Performance Qualification)
• IQ (Installation Qualification)
• OQ (Operational Qualification)
• PQ (Performance Qualification)
• Date
• Operator (who performed the qualification)
• Result (Pass/Fail + summary)
• Attachment (PDF report)
• Monitor calibration status to schedule recalibration and ensure instrument accuracy. Calibration Status:The user must be able to enter the date of the next calibration. Based on this date, a color code (green, orange, or red) will highlight this section to indicate whether the date is far away, approaching, or expired.An alert system will also be put in place to notify the person responsible when the expiration date is approaching. To receive this notification, they will need to configure the system by specifying the alert date and the person or persons who should receive it.Fields:Certificate (PDF upload)Expiry Date
• Calibration Status:The user must be able to enter the date of the next calibration. Based on this date, a color code (green, orange, or red) will highlight this section to indicate whether the date is far away, approaching, or expired.An alert system will also be put in place to notify the person responsible when the expiration date is approaching. To receive this notification, they will need to configure the system by specifying the alert date and the person or persons who should receive it.
• The user must be able to enter the date of the next calibration. Based on this date, a color code (green, orange, or red) will highlight this section to indicate whether the date is far away, approaching, or expired.
• An alert system will also be put in place to notify the person responsible when the expiration date is approaching. To receive this notification, they will need to configure the system by specifying the alert date and the person or persons who should receive it.
• Fields:Certificate (PDF upload)Expiry Date
• Certificate (PDF upload)
• Expiry Date
• Receive notifications for upcoming calibration or qualification renewals (see configuration system section)

Est-ce que tout ça c'est nécéssaire pour la v1 pour Algama ? 

D. Activities (Transformations/Events)

Goal:Log all actions performed on batches/samples for full traceability.

User Stories:

• As a Lab Technician, I want to: Log transformations (e.g., splits, mixes, dilutions) to track sample history and ensure reproducibility. I also want to track the instrument I use
• Log transformations (e.g., splits, mixes, dilutions) to track sample history and ensure reproducibility. I also want to track the instrument I use

 ActionDescriptionExampleReceiveLog a new batch into inventory.Batch A = 500 mL (new)ConsumeReduce the quantity of a specific item in a batch.Before: A = 500 mL → After: A = 480 mL (consumed 20 mL)SplitDivide a batch into sub-batches.A (100 µL) → A1 (30 µL) + A2 (30 µL) + A (40 µL)MoveChange the location of a batch or item.A (Fridge A) → A (Fridge B)CombineMerge multiple batches or items into a new batch.A (10 mL) + B (5 mL) → M1 (15 mL)DiscardRemove a batch or item (e.g., expired/contaminated).Batch A discarded (reason: contamination)DiluteAdjust the concentration of a sample by adding solvent.A (10 mL, 1M) → A (20 mL, 0.5M)ConcentrateReduce the volume of a sample to increase concentration.A (20 mL) → A (10 mL)RelabelUpdate batch/sample labels or tags.Add tag "Priority" to Batch A  - Transformation rules : are mentioned at the end of the document.         For each activity we have to mention: 

• List of Input items
• List of Output items
• List of Instruments
• Datetime [par defaut date du jour]
• Operator
• Description

- As an Admin, I want to:

• Generate reports of all transformations for audits and compliance checks (optional).

Pas dans la v1

4. KPI and Usage Statistics

• Track usage statistics of consumables and non-consumables.
• Log user actions with timestamps: PersonDate-time
• Person
• Date-time

Pas dans la v1

5. Hierarchical Display of Batches and Items

• Display batches and items in a single hierarchical table:

123456789+Batch1+Item1+Aliquot1+Aliquot2+Item2+Sample1 [m] [parents]+Batch2+Item1+Sample1 [m] [parents]Qu'est-ce qui fait la hierarchie ? Les split, combine, dilutes... ? Avoir des boutons pour afficher des bout de graph en mode workflow (pour les fils et parent et voir pour un global)

6. Automatic Item Sheet Creation

• If a new item is created by combining existing items (e.g., A + B → C), and C does not have an item sheet: Show a popup asking the user to create an item sheet for C.
• Show a popup asking the user to create an item sheet for C.

7. Units of Measurement

Celles qu'on a déjà + ce qui manque )CatégorieUnitéExemple d’usage concretVolumeLSolvants, milieux (ex: 1 L de PBS)mLTampons, cultures (ex: 50 mL de LB)µL (uL)Enzymes, ADN/ARN (ex: 2 µL de Taq)Volume (à ajouter)nLMicrofluidique / distributeurs HT (ex: 50 nL par puits)MassekgPoudres en vrac (ex: 1 kg NaCl)gRéactifs solides (ex: 250 g agarose)mgStandards, petites quantités (ex: 5 mg primer)Masse (à ajouter)µg (ug)ADN/ARN/protéines (ex: 10 µg d’ARN total)ngADN faible quantité (ex: 20 ng d’ADN plasmidique)LengthmTubing, films (ex: 2 m de tubing)cmMembranes/feuilles (ex: 10 cm de membrane)mmDiamètre, joints (ex: filtre 25 mm)Length (à ajouter)µm (um)Pore size filtre/membrane (ex: filtre 0.22 µm)Count (units)pcsConsommables (ex: 96 pcs tips)Count (à ajouter)cellsCulture cellulaire (ex: 1×10⁶ cells)copiesqPCR/NGS (ex: 2×10⁵ copies)CFUMicrobio (ex: 100 CFU)CatégorieUnitéExemple d’usage concretAmount (à ajouter)molChimie / solutions mères (ex: 0.1 mol)mmolPréparation solutions (ex: 5 mmol MgCl₂)µmolOligos, standards (ex: 20 µmol d’amorce)nmolOligos (ex: 5 nmol d’ADN)pmolqPCR/primers (ex: 10 pmol par réaction)CatégorieUnitéExemple d’usage concretConcentration (mass/vol)masse par volumeng/µLADN/ARN (ex: ADN = 50 ng/µL)µg/mLProtéines/ARN (ex: protéine = 200 µg/mL)mg/mLAnticorps / protéines (ex: Ab = 2 mg/mL)g/LMilieux / chimie (ex: glucose 10 g/L)Concentration (molaire)nombre de moles par volumeMSolutions stock (ex: Tris 1 M)mMBuffers/ions (ex: MgCl₂ 10 mM)µMOligos/ligands (ex: primer 10 µM)nMSondes (ex: probe 250 nM)Concentration (activité enzyme)la “puissance” enzymatique par volume.U/µLEnzymes (ex: Taq 5 U/µL)U/mLEnzymes en vrac (ex: DNase 1000 U/mL)Concentration (count/vol)la “puissance” enzymatique par volume.cells/mLComptage cellules (ex: 3×10⁵ cells/mL)copies/µLqPCR (ex: 1×10⁴ copies/µL) estimé par qPCR

8. Alert System

• Send alerts when: Maintenance or expiration (consommable) or calibration (instrument) dates are approaching.
• Maintenance or expiration (consommable) or calibration (instrument) dates are approaching.

Pas dans la V1

Configuration system

User roles

In the app, we need to configure several user roles

• Quality managerWill receive all notification (expiration dates ...)
• Will receive all notification (expiration dates ...)
• Operation manager
• Technician

Notifications

• Set up the notification: define the alert date for 30 or 40 days before the scheduled date.

Pas dans la v1

Transformation rules

1. Consume

Objective

Reduce the available quantity of a specific input item without creating a new scientific output entity.

Inputs

• Exactly 1 input entity required
• Allowed input : item ID

Mandatory input fields:

• Input Entity ID
• Available Quantity (already stored in the system)
• Quantity to Consume
• Unit
• description
• List of Instrument
• datatime
• operator

Outputs

• The system updates the remaining quantity of the input entity

Business Rules

• Consumed quantity must be greater than 0
• Consumed quantity must be less than or equal to available quantity
• Unit must match the stocked unit or follow allowed conversion rules
• If remaining quantity = 0, entity status may become: Exhausted

Traceability Rules

• Store before quantity
• Store consumed quantity
• Store after quantity
• Store operator, datetime, and reason
• Keep reference to the source entity

2. Split

Objective

Divide one input entity into multiple child entities.

Inputs

• Exactly 1 input entity required
• Allowed input: item ID

Mandatory input fields:

• Input Entity ID
• Available Quantity (already stored in the system)
• Unit
• description
• List of Instrument
• datatime
• operator

Outputs

• At least 2 output entities required
• Each output must have: Output ID Quantity Unit Location Label

                  expiration date                   note

Business Rules

• Sum of output quantities must be less than or equal to input quantity
• Remaining quantity handling must be configurable: either full split: input is closed and fully replaced by outputs or partial split: input remains open with reduced quantity
• All outputs must keep the same material identity as the parent unless explicitly allowed otherwise
• Units must be compatible

Traceability Rules

• Each output must store a parent reference to the original input
• The split activity must preserve genealogy: Parent → Child 1, Child 2, Child 3
• IDs must be unique

3. Combine

Objective

Merge several input entities into one new output entity.

Inputs

• Minimum 2 input entities required
• Allowed input types: items id (1....n)

Mandatory per input:

• Input Entity ID
• Quantity contributed
• Unit
• description
• List of Instrument
• datatime
• operator

Outputs

• Minimum 1 output entity
• Output fields: Output ID Output Quantity Output Unit Output Location Output Label date of expiration note

Business Rules

• At least 2 inputs required
• Output quantity must equal the sum of valid input quantities, unless loss is explicitly declared
• If loss is allowed, system must record: theoretical quantity actual quantity quantity loss reason
• Inputs may be: fully consumed partially consumed
• Combine must not be allowed across incompatible units without conversion

4. Dilute

Objective

Decrease the concentration of an input entity by adding a diluent.

Inputs

• Minimum 2 inputs required: 1 target entity to dilute1 diluent entity
• Allowed target : items ID
• Allowed diluent : item ID

Mandatory fields:

• item ID
• Target volume
• Initial concentration
• Diluent item ID
• Diluent added volume
• Final target volume
• Final target concentration or dilution factor
• description
• List of Instrument
• datatime
• operator

Outputs

New derived outputcreate a new diluted child entityMandatory output fields:

• Output ID
• Output quantity
• Output unit
• Output concentration
• Output location
• date of expiraton

Business Rules

• Diluent input is required
• Final concentration must be lower than initial concentration
• Final volume must be greater than initial volume
• Dilution factor must be calculable and stored
• the diluent consumed quantity must be deducted
• Input and diluent units must be compatible

Traceability Rules

• Output must reference: source entity diluent entity dilution factor initial and final concentration

5. Concentrate

Objective

Increase the concentration of an input entity by reducing solvent volume or applying a concentration process.

Inputs

• Exactly 1 item ID is required

Mandatory fields:

• Input Entity ID
• Initial volume
• Initial concentration
• Final volume
• Final concentration
• Concentration method (evaporation , Ultrafiltration, Lyophilization, Precipitation, Centrifugal concentration)=> optional
• description
• List of Instrument
• datatime
• operator

Outputs

- Create a new concentrated derived entityMandatory output fields:

• Output ID
• Output quantity
• Output unit
• Output concentration
• Output location
• date of expiration

Business Rules

• Final concentration must be higher than initial concentration
• Final volume must be lower than initial volume, unless method defines another mechanism
• Losses must be recorded when applicable
• Concentration method may be required from a controlled list (optiona)