High-level overview of the Toxicology feature: purpose, scope, and core concepts.

Overview

Toxicology in the medical laboratory identifies and quantifies toxins, drugs, and chemicals in biological samples. It is used to diagnose poisoning, monitor therapeutic drug levels, and detect substance abuse.

Toxicology

Toxicology provides the product foundation for managing toxicology-specific master data and report configuration. Before a toxicology workflow can be used in billing, report entry, or result interpretation, labs must define the underlying drug catalog, group drugs into panels, and maintain brand-specific drug collections. This setup ensures that toxicology tests use consistent substances, orderable groups, defaults, and reporting behavior across the workflow.

After the prerequisite master data is ready, a toxicology report/test is created from Profile & Report Management > Test List. When the test type is selected as Toxicology, the report parameter builder exposes toxicology components such as Screening, Confirmation, Prescription, Summary, History, Image, and Clinical Notes.

Prerequisites

Requirement	Why it matters	Where it is enforced
Drug master data must exist	Panels and brands are built by adding drugs; toxicology configuration cannot be meaningful without drug records	Drug Master / Panel Master module in `livehealth-frontend`; backend persistence in `livehealthapp` and `crelio-app`
Panel master data must exist when panel-based toxicology configuration is needed	A panel is a collection of drugs used together for toxicology testing	Panel Master UI and related backend APIs
Brand master data must exist when brand-based grouping is needed	A brand is also a collection, but it groups drugs based on the drug brand	Brand Master UI and related backend APIs
User must have access to Drug Master / Panel Master screens	The master setup is managed from the Quality Control area in the application sidebar	Frontend route/sidebar permissions and backend authorization
Toxicology test/report must be created with test type `Toxicology`	Toxicology-specific report components are available only after selecting the toxicology test type	Test List / Add New Test flow in `livehealth-frontend`

What Is It For

Frontend perspective

Provide Drug Master, Panel Master, and Brand Master screens under Drug Master / Panel Master.
Let users create, update, disable, download, and bulk-manage toxicology master records.
Let users build panels by searching and adding drugs to a panel.
Let users build brands by searching and adding drugs to a brand.
Show system default, custom, disabled, and all-record views where applicable.
Create a toxicology report/test by selecting test type Toxicology.
Add toxicology report components from the report parameter menu.
Configure Screening fields, billing availability, default drugs/panels/brands, and display ordering metadata.

Backend perspective

Persist drug, panel, and brand master data across livehealthapp and crelio-app.
Validate required fields such as drug name, panel name, panel code, and drug selection.
Maintain relationships between panels and drugs, and between brands and drugs.
Support system default lists and lab/custom records where applicable.
Persist toxicology report parameter configuration and component metadata for report entry and billing workflows.

Types / Modes

Type	Example	Runtime behavior	Notes
Drug	Amphetamine, Ketamine, Diazepam	Defines individual substances with test type, category, code, sample type, cut off, upper limit, and unit	Base prerequisite for panels and brands
Panel	Test Panel	Groups multiple drugs under a panel name and panel code	Can include reflex options such as screening reflex and prescription reflex
Brand	Test Brand 1	Groups drugs based on drug brand	Similar collection behavior to panels, but organized around brand context
Screening component	Screening	First-line toxicology component for quickly detecting possible presence of drugs/toxins	Can be configured with fields, defaults, and billing availability
Confirmation component	Confirmation	Definitive follow-up component used to verify an exact substance	Typically follows presumptive positive screening results
Prescription component	Prescription	Medication-history component for legally prescribed drugs	Helps explain expected positives
Summary component	Summary	Linked summary of Screening or Confirmation findings	Categorizes findings as consistent, inconsistent, prescribed but consistent, or prescribed but inconsistent
History component	History	Historical summary across previous toxicology reports	Can summarize the last 1 to 6 reports and link to Screening or Confirmation
Image component	Image	Image grid for report attachments or default images	Configures max rows, max columns, and upload slots
Clinical Notes component	Clinical Notes	Clinician observations and interpretation	Connects lab findings with patient condition

Structure Of Toxicology

Layer	What it stores or owns	Table / state / file	Why it exists
Drug master layer	Individual toxicology drug definitions	`Drug`	Provides the base drug catalog
Panel master layer	Collections of drugs grouped as panels	`Drug` with `is_panel = 1`	Supports panel-based toxicology setup using the same Drug table
Brand master layer	Brand-specific collections of drugs	`Brand` with `drugs = ManyToManyField(Drug)`	Supports brand-based toxicology setup
Toxicology report layer	Toxicology report/test configuration and components	`Profile & Report Management > Test List > Add New Test > Test Type: Toxicology > Report Parameters`	Defines report-entry behavior for screening, confirmation, prescription, summary, history, images, and clinical notes
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 toxicology report components
Backend service layer	APIs, validation, persistence, permissions	`Drug`, `Brand`, panel records via `Drug.is_panel = 1`, plus toxicology handling inside generic billing default and report-submit flows	Owns source-of-truth behavior for master data, billing defaults, and report submission

Master Data Model Notes

Panels are stored in the same Drug table as drugs, with is_panel set to 1.

Brands use the Brand table and maintain a many-to-many relationship with Drug.

Key Brand model fields:

name: brand name.
is_disabled: enables/disables the brand without deleting it.
lab: lab scope for the brand.
drugs: many-to-many mapping to Drug.
cpt_code: CPT code for the brand.
created_by / updated_by: activity ownership.

The Brand table uses unique_together = (("name", "lab"), ), so brand names are unique within a lab.

Key Features

Drug Master list with drug name, test type, drug category, drug code, sample type, cut off, upper limit, and unit.
Panel Master add/update flow with panel name, panel code, CPT code, drug search, selected-drug table, and reflex toggles.
Brand Master add/update flow with brand name, CPT code, drug search, and selected-drug table.
System default request actions for new drugs, panels, and brands.
Download and bulk-action support from master list pages.
Toxicology report parameter components for screening, confirmation, prescription, summary, history, images, and clinical notes.
Screening component configuration for report-entry fields, defaults, grouping/sorting metadata, and billing availability.
Confirmation component configuration with Screening-style sections plus Reflex controls.
Prescription component configuration for tracking prescribed patient drugs.
Summary component configuration linked to Screening or Confirmation findings.
History component configuration for historical summaries, chart display, summary classes, date format, and date filter.
Image component configuration for image-grid layout and upload slots.
Clinical Notes component configuration linked to Screening or Confirmation with drug-level note visibility.

Overview

On this page