Design Decisions
Key design constraints, architectural rationale, tradeoffs, and extensibility notes for Toxicology.
Toxicology Design Decisions
Use this page to capture why the feature was built this way, not only what the code does.
Design Intent
Toxicology is designed around a prerequisite-master-data model. Before a lab can reliably configure toxicology behavior, it needs a stable catalog of drugs and controlled collections of those drugs.
The design premise:
toxicology configuration should be built on explicit drug, panel, and brand masters instead of ad hoc free-text setup.
Decision Stack
Key Design Constraints
| Constraint | Why it is real | Architectural consequence |
|---|---|---|
| Toxicology drugs need consistent metadata | Cut off, upper limit, sample type, test type, and unit affect interpretation | Drug Master is the base source for toxicology setup |
| Panels and brands are collections, not standalone test facts | They depend on drugs already existing | Panel and Brand flows require searchable drug selection |
| Panels and brands group drugs for different reasons | Panels group drugs for testing workflow; brands group drugs by drug brand context | Separate Panel Master and Brand Master screens are maintained |
| Labs may need defaults and custom records | System defaults reduce setup work, while custom records support lab-specific needs | List tabs separate all/system/custom/disabled records |
| Master records can be operationally disabled | Records may need to stop being selectable without losing history | UI exposes disabled records and bulk/status actions |
Architectural Rationale
1. Drug Master is the foundation
Drug records are created before panels and brands because both collections depend on selecting existing drugs.
Why this was preferred
- avoids duplicate drug definitions inside every panel or brand,
- keeps toxicology cut off, upper limit, sample type, and unit data in one catalog,
- makes panel and brand setup easier to validate,
- gives downstream workflows a stable drug identity to reference.
Alternative we did not choose
Alternative: let panels and brands define drugs inline
Why it was not chosen:
- it would duplicate drug metadata,
- updates would drift across collections,
- validation would be harder,
- reporting and downstream mapping would become less reliable.
2. Panel Master and Brand Master are separate collection concepts
Panels and brands both collect drugs, but they answer different operational questions.
| Collection | Question it answers |
|---|---|
| Panel | Which drugs are grouped together for toxicology testing? |
| Brand | Which drugs are grouped based on drug brand context? |
Keeping them separate makes the UI clearer and keeps backend relationships easier to reason about.
Tradeoffs
| Tradeoff | Benefit | Cost / risk |
|---|---|---|
| Separate master screens | Clearer workflows for drugs, panels, and brands | Users must understand setup order |
| System default and custom lists | Faster onboarding while preserving lab-specific setup | Backend must preserve record ownership/source semantics |
| Collection mappings instead of inline drug data | Avoids duplication and drift | Requires drug records to exist first |
Extensibility Notes
- Add new toxicology metadata at the Drug Master layer when it describes an individual drug.
- Add new grouping behavior at the Panel Master or Brand Master layer when it describes a collection.
- Avoid duplicating drug metadata directly into panel/brand records unless it is a deliberate historical snapshot.
- Document exact API paths and model names once the
livehealthapp,crelio-app, andlivehealth-frontendsource paths are mapped.