Backend

Architecture Overview

Toxicology backend behavior is implemented across livehealthapp and crelio-app. These services own the APIs, validation, persistence, and mapping behavior for drug, panel, and brand master data.

The same backend surface also persists toxicology report/test configuration. Once a report is created with test type Toxicology, the report parameter configuration can store toxicology components such as Screening, Confirmation, Prescription, Summary, History, Image, and Clinical Notes.

For runtime report behavior in livehealthapp, toxicology passes through the generic billing and report-submit flows. billDefaultController and SubmitReport are not toxicology-specific endpoints; they are shared paths where toxicology-specific branches/config handling must be understood.

System Design Diagram

Storage & Models

Important storage note: toxicology report values are not stored in the MySQL report-value tables. Runtime toxicology component values are stored in MongoDB/DocumentDB in the ReportValue collection, keyed against the lab report ID. This applies to submitted component values such as Screening, Confirmation, Prescription, Summary, History, Image, and Clinical Notes. Master data and report configuration still follow their respective relational/configuration storage paths.

Primary model areas:

Drug master
Panel master
Brand master
Drug-to-panel mappings
Drug-to-brand mappings
Toxicology report/test metadata
Toxicology report parameter components
Screening selected-field configuration
Screening meta configuration: group by, sort by, order by
Screening defaults: drugs, panels, and brands added by default
Screening billing availability configuration
Confirmation reflex configuration
Prescription selected drug/panel/brand configuration
Summary linked component and summary type configuration
History linked component, report-count, display preference, date format, date filter, and ordering configuration
Image grid rows, columns, and default upload configuration
Clinical Notes linked component, field visibility, and drug-scope configuration

Key model locations:

livehealthapp: runtime billing/report paths where toxicology logic passes through generic flows.
crelio-app: PY-3 surfaces where migrated master/config APIs exist.
Exact file paths should be added after source mapping in the local checkout.

Core Backend Responsibilities

Concern	Backend responsibility
Source of truth	Persist drug, panel, and brand master records
Validation	Enforce required names/codes and required drug selection for collections
Permissions / scope	Restrict master-data actions to authorized users/labs
Persistence	Maintain panel-to-drug and brand-to-drug relationships
Audit / logging	TBD
Downstream sync	Make prerequisite master data available to toxicology configuration and reporting flows
Report components	Persist Screening, Confirmation, Prescription, Summary, History, Image, and Clinical Notes configuration
Screening behavior	Persist selected fields, defaults, billing availability, mandatory-drug behavior, and meta ordering
Confirmation behavior	Persist Screening-style configuration plus Reflex settings
Prescription behavior	Persist prescribed-drug configuration for patient medication history
Summary behavior	Persist linked Screening/Confirmation component and selected summary classifications
History behavior	Persist historical-summary settings and linked result component
Image behavior	Persist image-grid dimensions and default image attachments
Clinical Notes behavior	Persist linked result component, note fields, hidden flags, and all/selected-drug scope
Billing defaults	Apply toxicology-specific defaults and orderables during billing
Report submission	Add toxicology-specific component parsing inside the generic report-submit flow and persist submitted values into DocumentDB `ReportValue` records for the lab report

Runtime Engine / Processing Flow

Frontend submits create/update data for drug, panel, or brand.
Backend resolves lab/user context and validates the payload.
Backend persists the master record.
For panels and brands, backend persists the selected drug mappings.
Backend returns the updated record/list response to the frontend.

Toxicology report setup flow:

Frontend creates or updates a report/test with test type Toxicology.
Frontend adds toxicology report components from the Report Parameters tab.
Backend persists each component with its title and referring list.
For Screening, backend persists selected report-entry fields, labels, editability, and hidden behavior.
Backend persists Screening meta settings for grouping, sorting, and ordering.
Backend persists Screening defaults so selected drugs/panels/brands can be added when the test is billed.
If Available during Billing is enabled, backend exposes the selected orderable drugs/panels/brands to billing workflows.
For Confirmation, backend persists Reflex settings for screening reflex, prescription reflex, and bill-entry activation.
For Prescription, backend persists selected drugs/panels/brands used to track patient prescribed medications.
For Summary, backend persists the linked Screening/Confirmation component and selected summary types.
For History, backend persists the linked component, previous-report count, display type, summary types, date format, date filter, and ordering.
For Image, backend persists grid dimensions and uploaded/default image metadata.
For Clinical Notes, backend persists linked component, visible fields, labels, hidden flags, and all-drugs/selected-drugs scope.

Billing-time toxicology behavior:

Billing opens or prepares the toxicology test.
Billing reads the test/report parameter configuration.
Screening defaults are resolved from configured drugs, panels, or brands.
If Available during Billing is enabled, configured orderable drugs/panels/brands are exposed to the billing modal.
If Drugs Mandatory is enabled, billing must enforce drug selection before continuing.
Confirmation reflex settings decide whether confirmation drugs should be added automatically or only when requested at bill entry.
Prescription configuration can expose prescribed/orderable drugs, panels, or brands for patient medication history capture.
The resulting toxicology component defaults/orderables are attached to the bill/order context for report entry.

Report-entry toxicology behavior in the generic submit flow:

Report entry loads the billed toxicology test and component configuration.
User-entered values for Screening, Confirmation, Prescription, Summary, History, Image, and Clinical Notes are submitted.
The generic submit flow receives the structured component payload.
Screening/Confirmation rows persist drug-level values such as cut off, result, interpretation, upper limit, name, and reflex-related fields into the DocumentDB ReportValue collection for the lab report.
Prescription persists prescribed drug context.
Summary persists linked-component summary classifications.
History persists generated or submitted historical-summary configuration/output.
Image persists uploaded image metadata or report image references.
Clinical Notes persists drug-level notes linked to the configured component.
Report status, audit fields, and downstream report rendering data are updated as part of the normal report submission flow.

Shared Flow Touchpoints

Generic flow	Stack	When it runs	Toxicology-specific behavior
`billDefaultController`	`livehealthapp`	Billing / bill preparation	Toxicology config contributes default drugs/panels/brands, billing-available orderables, mandatory-drug behavior, and reflex-at-billing behavior
`SubmitReport`	`livehealthapp`	Report entry submit	Toxicology payload contains component values and linked component data that must be parsed and persisted correctly

Toxicology behavior in `billDefaultController`

billDefaultController is a generic billing default path. The toxicology-specific concern is what gets added to the bill/report-entry context when the billed test has test type Toxicology.

Developer checklist:

Load the billed test and identify whether it is a toxicology test.
Read report parameter configuration for Screening, Confirmation, Prescription, and related components.
Resolve Screening Defaults into bill/report-entry rows.
Expand configured panels/brands into their mapped drugs where required.
Respect Available during Billing by exposing only configured orderable drugs/panels/brands.
Respect Drugs Mandatory by blocking or flagging incomplete billing input where configured.
Apply Confirmation reflex options:
- Screening Reflex
- Prescription reflex
- Ask at Bill Entry to Enable Reflex
Carry enough metadata forward so the generic report-submit flow can map submitted values back to the correct toxicology component.

Toxicology behavior in `SubmitReport`

SubmitReport is a generic report-entry persistence path. The toxicology-specific concern is that toxicology components are structured payloads with linked components, defaults, drug rows, summary classifications, image grids, and clinical-note scopes.

Developer checklist:

Resolve the report/test and confirm toxicology component configuration.
Map submitted rows back to their component: Screening, Confirmation, Prescription, Summary, History, Image, or Clinical Notes.
Preserve linked component relationships, especially:
- Summary -> Screening/Confirmation
- History -> Screening/Confirmation
- Clinical Notes -> Screening/Confirmation
Persist drug-level values with the configured labels/visibility semantics.
Persist uploaded image metadata for Image grids.
Preserve summary classifications:
- Consistent
- Inconsistent
- Prescribed but Consistent
- Prescribed but Inconsistent
Keep report rendering output consistent with component Meta settings such as group by, sort by, order by, date format, and date filter.

Important Toxicology Snippets (Backend)

Add focused snippets here after the exact livehealthapp and crelio-app files are mapped.

High-value snippets to include:

generic billing default branch that identifies toxicology tests.
toxicology logic that resolves Screening defaults.
toxicology logic that expands panels/brands into drugs.
toxicology logic for Available during Billing and Drugs Mandatory.
toxicology logic for Confirmation reflex toggles.
generic report-submit parsing for toxicology components.
toxicology persistence for Screening/Confirmation drug-level rows.
toxicology persistence for Summary, History, Image, and Clinical Notes linked components.

API / URL Touchpoints

This table intentionally lists only URL patterns verified in the local livehealthapp / crelio-app checkout. Component fields such as Screening defaults, billing availability, Summary types, History settings, Image grid settings, and Clinical Notes visibility are configuration payload fields, not separate endpoints.

Stack	URL pattern	Method / view	Source	Toxicology-specific purpose
`livehealthapp`	`^billing/$`	`billDefaultController`	`livehealthapp/livehealthapp/urls.py`	Shared billing path where toxicology defaults/orderables are applied when a toxicology test is billed
`livehealthapp`	`^get-lab-report/$`	`SubmitReport`	`livehealthapp/reports/urls.py`	Shared report-submit path where toxicology component payloads are submitted
`livehealthapp`	`^dataPartialFromToxDevice/$`	`GetToxDataForPending.as_view()`	`livehealthapp/livehealthapp/urls.py`, `livehealthapp/devices/views.py`	Receives pending toxicology device data and maps it into report values
`livehealthapp`	`^integration/tox/add_drugs_into_report/$`	`add_mirco_tox_params_in_report`	`livehealthapp/livehealthapp/urls.py`, `livehealthapp/labs/integration_functions.py`	Integration path to add toxicology drugs into report values
`crelio-app`	`report/<int:report_id>/drugs/default`	`DrugReportValuesUpdateView`	`crelio-app/report/urls.py`, `crelio-app/report/views/drug_report_values.py`	Fetches existing Screening, Confirmation, and Prescription drug values from DocumentDB
`crelio-app`	`report/<int:report_id>/drugs/update`	`DrugReportValuesUpdateView`	`crelio-app/report/urls.py`, `crelio-app/report/views/drug_report_values.py`	Updates default drugs in DocumentDB for unfilled toxicology reports
`crelio-app`	`related-drugs/<int:primary_drug_id>`	`FetchRelatedDrugsView`	`crelio-app/report/urls.py`	Fetches related/reflex drugs for toxicology
`crelio-app`	`related-drugs/new`	`RelatedDrugsView`	`crelio-app/report/urls.py`	Creates related/reflex drug mapping
`crelio-app`	`related-drugs/update`	`RelatedDrugsView`	`crelio-app/report/urls.py`	Updates related/reflex drug mapping
`crelio-app`	`related-drugs/delete/<int:related_drug_id>`	`RelatedDrugsView`	`crelio-app/report/urls.py`	Deletes related/reflex drug mapping
`crelio-app`	`device-results-validation/tox/new`	`ToxDeviceResultsForValidation`	`crelio-app/interfacing/urls.py`	Saves toxicology device results for validation
`crelio-app`	`device-results-validation/tox/<int:device_id>`	`FetchToxDeviceResultsForValidation`	`crelio-app/interfacing/urls.py`	Fetches toxicology device results for validation
`crelio-app`	`device-results-validation/release-tox-parameters`	`ToxParameterReleaseView`	`crelio-app/interfacing/urls.py`	Releases reviewed toxicology device parameters
`crelio-app`	`support/tox-cache/clear/<int:lab_id>`	`ClearToxicologyCacheView`	`crelio-app/support/urls.py`	Clears toxicology cache for a lab

Entity Creation / Side Effects

Saving panels and brands creates or updates collection mappings to drug records.

Saving Screening defaults creates report-parameter configuration that can auto-add selected drugs or panels once the toxicology test is billed. Enabling Available during Billing makes selected drugs, panels, or brands available on the billing modal. Any audit logs, activity logs, queueing, or system-default request behavior should be documented after backend source paths are confirmed.

Confirmation reflex configuration can add confirmation drugs from screening or prescription context. Prescription configuration tracks prescribed patient drugs. Summary configuration depends on a linked Screening or Confirmation component so it can summarize the correct result set.

History configuration also depends on a linked component and generates historical context across previous reports. Image configuration stores report image-grid behavior. Clinical Notes configuration links note fields to a result component and controls whether notes apply to all drugs or selected drugs.

Backend

On this page