Overview
High-level overview of the Molecular feature: purpose, scope, and core concepts.
👤 Mohammad Ashfaque Alam📅 Updated: May 19, 2026📁 Molecular
Overview
Molecular diagnostics in the medical laboratory detects and identifies genetic material, pathogens, and organisms in biological samples using techniques such as PCR. It is used to diagnose infectious diseases, determine antibiotic resistance patterns, and guide treatment decisions.
Molecular
Molecular provides the product foundation for managing molecular-specific master data and report configuration. Before a molecular workflow can be used in billing, report entry, or result interpretation, labs must define the underlying gene catalog, maintain antibiotic records, and build organisms that link genes and antibiotics. This setup ensures that molecular tests use consistent genetic markers, organisms, antibiotic resistance patterns, and reporting behavior across the workflow.
After the prerequisite master data is ready, a molecular report/test is created from Profile & Report Management > Test List. When the test type is selected as Molecular, the report parameter builder exposes molecular components such as Gene, Organism, Antibiotic Resistance, and Molecular Pivot.
Prerequisites
| Requirement | Why it matters | Where it is enforced |
|---|---|---|
| Gene master data must exist | Antibiotic Resistance components require gene records; molecular report configuration cannot be meaningful without gene records | Gene Master module in livehealth-frontend; backend persistence in livehealthapp and crelio-app |
| Antibiotic master data must exist when resistance-based molecular configuration is needed | An antibiotic record represents a drug used to determine susceptibility patterns | Antibiotic Master UI and related backend APIs |
| Organism master data must exist when organism-based molecular configuration is needed | An organism is a microorganism that may be detected; organisms are linked to antibiotics through antibiogram mappings | Organism Master UI and related backend APIs |
| User must have access to Drug Master / Panel Master screens | The master setup for genes, antibiotics, and organisms is managed from the Drug Master / Panel Master area in the application sidebar | Frontend route/sidebar permissions and backend authorization |
Molecular test/report must be created with test type Molecular | Molecular-specific report components are available only after selecting the molecular test type | Test List / Add New Test flow in livehealth-frontend |
What Is It For
Frontend perspective
- Provide Gene Master, Antibiotic Master, and Organism Master screens under
Drug Master / Panel Master. - Let users create, update, disable, download, and bulk-manage molecular master records.
- Let users build antibiotic resistance mappings by linking antibiotics to genes.
- Let users define organism-to-antibiotic relationships (standard antibiogram) and molecular organism-to-antibiotic relationships (molecular antibiogram).
- Show system default, custom, disabled, and all-record views where applicable.
- Create a molecular report/test by selecting test type
Molecular. - Add molecular report components from the report parameter menu.
- Configure Gene and Organism fields, billing availability, and display ordering metadata.
Backend perspective
- Persist gene, antibiotic, and organism master data across
livehealthappandcrelio-app. - Validate required fields such as gene name, antibiotic name/category/code/unit, and organism name/category/code.
- Maintain relationships between genes and antibiotics through the
AntibioticResistancetable. - Maintain relationships between organisms and antibiotics through the
OrganismAntibioticstable. - Maintain molecular-specific organism-to-antibiotic ordering and active state through the
MolecularOrganismAntibioticstable. - Support system default lists and lab/custom records where applicable.
- Persist molecular report parameter configuration and component metadata for report entry and billing workflows.
Types / Modes
| Type | Example | Runtime behavior | Notes |
|---|---|---|---|
| Gene | mecA, blaCTX-M, rpoB | Defines individual genetic markers with name, code, gene type, cut off, description, and CPT code | Base prerequisite for antibiotic resistance configuration; linked to antibiotics through AntibioticResistance |
| Antibiotic | Ciprofloxacin, Cefotaxime, Amikacin | Defines antimicrobial drugs with name, category, code, method, unit, sample type, device name, and dosage | Shared between Gene and Organism master contexts |
| Organism | E. coli, S. aureus, K. pneumoniae | Defines microorganisms with name, category, code, cut off, sample type, and description; linked to antibiotics through OrganismAntibiotics and MolecularOrganismAntibiotics | Base entity for antibiogram and molecular pivot results |
| Gene component | Gene | First-line molecular component for detecting genetic markers | Configured with Cut Off, Result, Interpretation, and Name fields |
| Organism component | Organism | Molecular component for identifying detected organisms | Configured with Name, Result, Interpretation, Cut Off, and Viral Load fields |
| Antibiotic Resistance component | Antibiotic Resistance | Linked to a Gene component; shows resistance patterns for detected genes | Linked to all Gene components in the test; supports Show All / Only Resistant / Only Sensitive filter; has a Calculate button |
| Molecular Pivot component | Molecular Pivot | Summary-style pivot of Antibiotic Resistance findings | Linked to all Antibiotic Resistance components; supports Group By, Sort By, and Order By metadata |
Structure Of Molecular
| Layer | What it stores or owns | Table / state / file | Why it exists |
|---|---|---|---|
| Gene master layer | Individual molecular gene definitions | Gene | Provides the base gene catalog for genetic marker detection |
| Antibiotic master layer | Antimicrobial drug definitions | Antibiotic | Provides the base antibiotic catalog shared by gene and organism resistance workflows |
| Organism master layer | Microorganism definitions with antibiogram and molecular mappings | Organism with OrganismAntibiotics and MolecularOrganismAntibiotics | Represents detected organisms and their susceptibility patterns |
| Antibiotic resistance relationship layer | Gene-to-antibiotic mappings | AntibioticResistance (gene_id, antibiotic_id) | Links genes to their associated antibiotics for resistance component behavior |
| Molecular organism relationship layer | Organism-to-antibiotic mappings with sequence and active state | MolecularOrganismAntibiotics (organism_id, antibiotic_id, sequence, is_active) | Maintains ordered, activatable molecular antibiogram entries per organism |
| Molecular report layer | Molecular report/test configuration and components | Profile & Report Management > Test List > Add New Test > Test Type: Molecular > Report Parameters | Defines report-entry behavior for gene detection, organism identification, antibiotic resistance, and pivot views |
| Frontend UI layer | Lists, modals, filters, bulk actions, add/update flows | Drug Master / Panel Master screens and Test List > Report Parameters builder | Lets users manage prerequisite master data and configure molecular report components |
| Backend service layer | APIs, validation, persistence, permissions | Gene, Antibiotic, Organism, AntibioticResistance, OrganismAntibiotics, MolecularOrganismAntibiotics plus molecular handling inside generic report-submit flows | Owns source-of-truth behavior for master data, billing defaults, and report submission |
Master Data Model Notes
Genes are stored in the Gene table with a many-to-many relationship to Antibiotic through the AntibioticResistance through-table.
Organisms maintain two relationships to antibiotics:
OrganismAntibiotics: standard antibiogram mappings.MolecularOrganismAntibiotics: molecular-specific ordered and activatable mappings withsequenceandis_activefields.
Key Gene model fields:
name: gene name; unique within a lab (unique_together = (("name", "lab"),)).code: gene code.gene_type: gene type classification.cut_off: numeric cut-off value used for result interpretation.description: optional description.cpt_code: CPT billing code.lab: lab scope for the gene.is_disabled: enables/disables the gene without deleting it.antibiotics: many-to-many mapping toAntibioticthroughAntibioticResistance.
Key Antibiotic model fields:
name: antibiotic name; unique within a lab.category: antibiotic category (e.g.,Third-generation cephalosporins,Fluoroquinolones).code: antibiotic code; commonly uses WHO ATC codes such asJ01DD01.method: optional testing method.unit: unit of measurement.sample_type: optional sample type.device_name: optional device name for instrument-specific mapping.dosage: optional dosage field.cpt_code: CPT billing code.is_disabled: enables/disables the antibiotic without deleting it.
Key Organism model fields:
name: organism name; unique within a lab.category: organism category.code: organism code.cut_off: numeric cut-off value.sample_type: optional sample type.description: optional description.antibiotics: many-to-many mapping toAntibioticthroughOrganismAntibiotics.is_disabled: enables/disables the organism without deleting it.
Key Features
- Gene Master list with gene name, gene code, description, and type.
- Antibiotic Master list with antibiotic name, sample type, antibiotic category, antibiotic code, and status.
- Organism Master list with organism name, sample type, organism category, organism code, and status.
- System default request actions for new genes, antibiotics, and organisms.
- Download and bulk-action support from master list pages.
- Molecular report parameter components for gene detection, organism identification, antibiotic resistance, and molecular pivot.
- Gene component configuration for report-entry fields, labels, editable and hidden behavior.
- Organism component configuration with Viral Load field in addition to standard gene fields.
- Antibiotic Resistance component configuration linked to Gene components with Show All / Only Resistant / Only Sensitive filtering.
- Molecular Pivot component configuration linked to Antibiotic Resistance components with Group By, Sort By, and Order By metadata.
- Detection logic uses inverted cut-off semantics: a result value at or below the cut-off means
Detectedand a value above meansNot Detected. - Device mapping support for both Gene and Organism through dedicated device-gene and device-organism mapping views.