Design Decisions

Overview

The Toxicology Reflex Management workflow was designed to automate confirmation testing workflows while still giving laboratories complete control over:

• Reflex behavior
• Billing-time decisions
• Device-driven workflows
• Drug relationship configuration
• Confirmation processing

The architecture intentionally separates:

• Frontend reflex orchestration
• Backend metadata persistence
• Device result processing
• Reflex execution logic

This separation keeps the system flexible, scalable, and easier to maintain.

High-Level Design Goals

The Reflex Management system was designed with the following goals:

Why Reflex Relationships Are Configured at Drug Level

Reflex relationships are configured inside:

Drug Master → Related Drugs

instead of directly inside report configuration.

Reasoning

This design allows:

• Drug relationships to be reusable across tests
• Centralized reflex configuration
• Easier maintenance for laboratories
• Consistent reflex behavior across reports

Example:

This configuration can then be reused by multiple Toxicology reports.

Why Reflex Settings Exist in Confirmation Component

The Screening and Prescription Reflex toggles are stored inside Confirmation Component Meta

Reasoning

The Confirmation component acts as the final destination for:

• Reflex drugs
• Prescription drugs
• Auto-confirmation workflows

Since Confirmation is the destination component, it becomes the central place to:

• Enable/disable reflex workflows
• Control billing-time overrides
• Define confirmation-specific behavior

Why Billing-Time Reflex Control Was Added

The setting Ask at Bill Entry to Enable Reflex was introduced to give laboratories operational flexibility.

Problem

Different patients and tests may require different reflex behavior even for the same report configuration.

Example:

• One patient may require reflex confirmation
• Another patient may not

Hardcoding reflex execution at configuration level was too restrictive.

Solution

Billing-time reflex control allows users to:

• Enable Screening Reflex per bill
• Disable Screening Reflex per bill
• Enable Prescription Reflex per bill
• Disable Prescription Reflex per bill

without changing report configuration.

Why Prescription Reflex Is Frontend-Driven

Prescription Reflex works differently from Screening Reflex.

Design Decision

The frontend automatically injects Prescription drugs into the confirmation component payload before sending the billing request.

Why This Approach Was Chosen

This keeps:

• Reflex orchestration in frontend
• Metadata persistence in backend

Benefits:

Why Screening Reflex Is Backend-Driven

Screening Reflex depends on:

• Device results
• Cutoff validation
• Runtime positivity checks

These values are only available after the device sends results.

Therefore the workflow is handled inside:

POST dataPartialFromToxDevice/

instead of during billing.

Screening Reflex Workflow

Device Sends Result
    ↓
Compare Result With Cutoff
    ↓
Check Reflex Enabled
    ↓
Fetch Related Drugs
    ↓
Insert Into Confirmation

Why Reflex Drugs Are Stored Directly in Confirmation

When reflex conditions are satisfied, the system directly inserts Reflex drugs into Confirmation Component instead of storing them separately.

Reasoning

This design simplifies:

• Report rendering
• Confirmation processing
• User workflows
• Device interfacing

The Confirmation component becomes the single source of truth for:

• Manual confirmation drugs
• Prescription reflex drugs
• Screening reflex drugs

Why Reflex Drugs Are Marked Using is_reflex

Reflex-added drugs are stored using:

"is_reflex": 1

Purpose

This helps distinguish:

This flag helps with:

• UI rendering
• Auditing
• Future workflow customization
• Reflex tracking

Why Duplicate Prevention Exists

Before inserting reflex drugs into Confirmation, the system checks existing drugs.

Reasoning

Without duplicate prevention:

• Multiple device syncs could repeatedly add the same Reflex drugs
• Confirmation component would become inconsistent
• Report rendering could break

Current Logic

The system:

• Reads existing Confirmation drugs
• Compares IDs
• Inserts only new reflex drugs

Why Reflex State Is Stored Per Billing

Billing-time reflex selections are stored inside:

ReflexTestDetails

instead of global configuration.

Reasoning

This allows:

• Per-patient reflex control
• Per-bill reflex overrides
• Runtime flexibility
• Safe auditability

Example:

Both bills can use the same report configuration while behaving differently.

Why Device Drug Mapping Exists

The device payload contains:

{
  "testName": "Ketamine"
}

This value may not directly match internal drug structures. Therefore DeviceDrugs mapping is used.

Benefits

• Supports multiple devices
• Supports vendor-specific naming
• Allows custom mappings per lab
• Decouples device terminology from internal drug models

Why Toxicology Uses Component-Based Metadata

Toxicology reports are stored using component_instances instead of flat report structures.

Reasoning

This architecture allows:

• Dynamic components
• Flexible workflows
• Multi-stage testing
• Runtime metadata manipulation
• Independent component rendering

Why only_existing_drugs Logic Exists

Some laboratories only want reflex processing for:

• Drugs billed during order entry

and not for all device results. The only_existing_drugs setting ensures:

• Reflex processing occurs only for billed drugs
• Unexpected device results do not modify reports

Workflow Architecture

High-Level Workflow Diagram

End-to-End Reflex Lifecycle

Configure Drug Relationships
    ↓
Configure Reflex Settings
    ↓
Bill Toxicology Test
    ↓
Store Toxicology Metadata
    ↓
Store Billing-Time Reflex State
    ↓
Receive Device Results
    ↓
Validate Screening Positivity
    ↓
Fetch Reflex Drugs
    ↓
Update Confirmation Component
    ↓
Finalize Toxicology Report

Key Architectural Decisions Summary

Important Notes

• Prescription Reflex is initialized during billing
• Screening Reflex is initialized during device result processing
• Confirmation acts as the central reflex destination component
• Billing-time reflex overrides are respected throughout the workflow
• Reflex workflows support both automated and user-controlled execution
• Device-driven workflows are isolated from billing workflows for better scalability