Skip to main content
Version: 3.0.1

SDD Configuration

Back end configurations

Environment Variables

Environment variables and secrets are managed through Laravel Vapor. Configuration is categorized into standard variables and secrets (sensitive credentials).

Important: Variables should be changed via Deployment Console, not Vapor interface directly. Deployments are immutable - changes require redeployment.

Variable Categories Summary:

CategoryCountSecurity Level
Application Core7Standard
Database (Audit)3Restricted
Session2Standard
Pusher (Real-time)7Restricted
Cognito (Auth)13Restricted
Monitoring5Standard
Security3Restricted
Email2Standard
Secrets10Highly Restricted

Full Reference: Complete environment variable listings are documented in SDS Configuration Reference.

Client Configuration
Usage of Client configuration

Client configuration in a PCR.AI system involves setting up and customizing the system. It includes adjusting interface settings, importing configurations, and personalizing preferences to meet specific laboratory needs. The configuration covers categories such as login and user management, data import, data export, display preferences, result editing and management, Westgard settings, and showing or hiding certain features.

High Level Use Case Diagram

image19


Import Configuration
Site-Based S3 Folder Structure

When the multi_site_feature is enabled, each site receives a dedicated S3 folder structure for run file import and export operations.

S3 Folder Hierarchy (per site):

{client-bucket}/
└── {site-name}/
├── toPcrai/ # Import folder - monitored for new run files
├── Processing/ # Temporary folder during import processing
├── Problem_Files/ # Failed imports moved here for review
├── LIMS_Reports/ # Export destination for LIMS results
└── archive/ # Successfully processed files archived here

Configuration Settings:

SettingTypeDescription
multi_site_featureBooleanEnables site-level S3 folder isolation
s3_preserve_structureBooleanPreserves source folder hierarchy in archive
s3_folder_nameStringCustom folder name override (default: site name)

Import Flow:

  1. Files placed in {site}/toPcrai/ trigger S3 event notification
  2. Lambda moves file to {site}/Processing/ during import
  3. On success: file archived to {site}/archive/
  4. On failure: file moved to {site}/Problem_Files/ with error log

Related Requirements:


Control Labels Configurations
Usage of Control Labels

Ability to specify how the run file sample label should interact with the system.

How this works

This configuration is used to establish a link between the run file label and the system Role. By employing this configuration, the system can effectively identify relevant observations

How does the user see the Control Labels Configurations?

image20

Excel Configurations

Excel format and required data are as follows:

Sheet Name : Control Labels

Column Names :ROLEROLE TYPEMIXIS EXTRACTEDBACKUP MIXESLABELS IN IMPORTED RUNFILE
Examples :CCPCHDV | HEV | HEVFNCC1 | CC2
Examples :PECPCAll mixesYLO POS | HI POS | POS
Examples :NECNCAll mixesYNEC
Examples :NTCNCAll mixesNNTC
Description :Role nameType of the RoleRelated mixesIs role extracted or not (Y/N)Backup mixesLabels in run file
Excel Configurations

Excel format and required data are as follows:

Sheet Name : Combined Outcomes

Column Names :ROLEOUTCOME TYPEWELL ERROR CODE / LIMS CODETARGET ERROR CODETARGET TO HAVE ERRORMIXIC_FAILEDTARGETRESULTMINIMUM CTMAXIMUM CTMINIMUM QUANTITYMAXIMUM QUANTITYGROUP
Examples :PatientErrorDO_NOT_EXPORTVZVFALSEQVZVPos38501
Examples :PatientErrorDO_NOT_EXPORTCONTROL_CLSDISC_TARGETSARS E geneVZVFALSEQIPCAny1
Description :Role name Patient / ControlOutcome Type
Error / LIMS
Suitable Error Code/ Lims CodeTarget error code should be able to fill target level error when error typed outcome is selected and non sample type role is selected (This is optional )This should be able to define the target which should get the error when control typed role is selected (This is optional )MIX nameWhen applying the Combined Outcome Rule to a well, if the IC Failed option is true, an error is expected. If the IC Failed option is false, no error is expected.Target NamesResult of the outcome (Pos, Neg, or Any)The Minimum CT Value to trigger thisThe Maximum CT Value to trigger thisfor configure outcomes for targets based on observation minimum quantityfor configure outcomes for targets based on observation maximum quantityUse for the sort by combine outcomes Group
Alerts Configurations
The usage of the alert feature

To enhance the functionality of the Trends Report by providing the user with the ability to set and view alerts based on defined outcomes and their respective thresholds

The Alert feature serves the following purpose:
Alerts:

Alerts enable users to monitor trends data and receive notifications when configured thresholds are exceeded.


How alerts stored?

Alerts are stored in the database with the following structure:

Alert Configuration Table:

FieldTypeDescription
idUUIDUnique alert identifier
nameStringUser-defined alert name
conditionEnumComparison operator (greater than, less than, equals)
thresholdDecimalThreshold value to trigger alert
mix_idFKTarget mix (nullable for all mixes)
target_idFKTarget target (nullable for all targets)
outcomeStringOutcome type to monitor
schedule_frequencyEnumdaily, weekly, monthly
rolling_periodBooleanUse rolling time period vs fixed
rolling_daysIntegerNumber of days for rolling period
enabledBooleanAlert active status
site_idFKSite scope (nullable for global)
created_byFKUser who created alert
created_atTimestampCreation timestamp
updated_atTimestampLast modification timestamp

Related Requirement: REQ-REPORTS-013


How/When Alerts are triggered?

Alerts are evaluated in two contexts:

1. After Run Analysis (Real-time)

  • When a run completes analysis, relevant alerts are evaluated
  • Compares current trends data against configured thresholds
  • Triggers immediately if threshold exceeded

2. Scheduled Evaluation (Batch)

  • Scheduled job runs at configured frequency (daily, weekly, monthly)
  • Evaluates all enabled alerts against aggregated trends data
  • Triggers notifications for any threshold breaches

Trigger Workflow:

  1. Alert condition evaluated against trends data
  2. If threshold exceeded:
    • Create notification record in database
    • Send email to configured recipients (if email enabled)
    • Display in system notification area
  3. Notification includes: alert name, triggered value, threshold, timestamp

Related Requirement: REQ-REPORTS-014


How aggregation works?

Alerts support two aggregation modes for trends data evaluation:

1. Fixed Period Aggregation

  • Evaluates data within a specific date range
  • Used for point-in-time threshold checks
  • Example: "Alert if positive rate > 5% this month"

2. Rolling Period Aggregation

  • Evaluates data over a rolling window (e.g., last 30 days)
  • Window moves forward with each evaluation
  • Smooths out daily variations for trend detection
  • Example: "Alert if 7-day rolling average CT > 35"

Aggregation by Scope:

  • Per-Mix: Aggregate trends data filtered by specific mix
  • Per-Target: Aggregate trends data filtered by specific target
  • Per-Outcome: Aggregate by outcome type (Positive, Negative, etc.)
  • Per-Site: Multi-site deployments can scope alerts to specific sites or global

Schedule Frequency Impact:

FrequencyAggregation WindowUse Case
DailyPrevious 24 hours or rolling N daysRapid detection
WeeklyPrevious 7 days or rolling N daysTrend smoothing
MonthlyPrevious month or rolling N daysLong-term monitoring

Related Requirement: REQ-REPORTS-013


Cross Contamination Limits Configurations

CT value thresholds used by the ADJ (Adjacent) rule to detect potential cross-contamination between adjacent wells.

Data Elements:

ColumnDescriptionValidation
MixThe assay mix for this limitRequired, must exist in Mix configuration
TargetThe specific target within the mixRequired, must exist for selected mix
Potential ContaminatedCT threshold for potentially contaminated wellNon-decimal numeric, minimum 1
Potential ContaminatingCT threshold for contaminating sourceNon-decimal numeric, minimum 1
Quant/CtMode selector (CT or Quantity)CT: non-decimal, Quant: decimal min 0.0000000001

Design Notes:

  • Enforces Potential Contaminated > Potential Contaminating
  • Only allows adding limits for targets without existing limits
  • Used by ADJ rule during analysis to flag potential contamination
  • All changes logged to audit trail

Related Requirement: REQ-KITCFG-013


Curve Control Limits Configurations

Upper and lower CT bounds used by the BCC (Baseline Curve Control) rule for curve control validation.

Data Elements:

ColumnDescriptionValidation
MixThe assay mix for this limitRequired
TargetThe specific target within the mixRequired
Sample RoleThe control role (e.g., CC, PEC)Required
Lower Bound CtMinimum acceptable CT valuePositive non-zero
Upper Bound CtMaximum acceptable CT valuePositive non-zero, must be > Lower Bound

Design Notes:

  • BCC rule triggers "curve control out of expected range" error when control CT falls outside bounds
  • Supports bulk addition for multiple mix/target/role combinations
  • Each bound change logged separately to audit trail

Related Requirement: REQ-KITCFG-014


Delta CT Configurations

Target pairs and CT difference thresholds used by the Delta CT rule to detect unexpected variation between related targets.

Data Elements:

ColumnDescriptionValidation
Target PairFormatted as "Target A vs Target B"Both targets must exist
ValueMaximum allowable CT differencePositive non-zero numeric

Design Notes:

  • Delta CT rule triggers BAD_CT_DELTA error when difference exceeds threshold
  • Import ignores rows with non-existent targets or empty values
  • Prevents duplicate target pair configurations
  • Supports Excel import/export

Related Requirement: REQ-KITCFG-019


Error Codes Configurations

Definitions and classifications of error codes used throughout the analysis workflow.

Data Elements:

ColumnDescriptionValues
CodeUnique error identifierString, immutable after creation
MessageUser-facing error descriptionFree text
TypeError classificationClassification category
AffectsScope of errorWell, Target
LIMS ExportInclude in LIMS exportBoolean
Control ErrorFlag as control-specificBoolean
Westgard ErrorFlag as Westgard-relatedBoolean
Prevents AnalysisBlocks further analysisBoolean
IgnoredHide from run file reportsBoolean
Causes Missing MixesTriggers missing mix statusBoolean
InhibitedMarks as inhibition-relatedBoolean

Design Notes:

  • Error codes can be ignored but not deleted (preserves historical data)
  • Ignored codes hidden from run file reports
  • Supports filtering by code, type, and prevents-analysis flag
  • New codes require: code, message, type, affects, prevents analysis

Related Requirement: REQ-KITCFG-005


Error Resolutions Configurations

Resolution options for quality control errors, including affected wells and outcome assignments.

Data Elements:

ColumnDescriptionValues
Error MessageThe error this resolution applies toMust exist in Error Codes
Resolution MessageUser-facing resolution descriptionFree text
Affected WellsWells impacted by resolutionLIMS status, Error code, or "All Wells"
Rules SkippedRules to skip on re-analyzeMulti-select rule list
OutcomeResult after resolutionConfigurable outcome
DefaultSet as default resolutionBoolean
Affected Well TypeType of affected wellsConfigurable
Resolution LevelScope of resolutionWell, All Observations, Discrepant Observations

Design Notes:

  • Resolutions grouped by error message in UI
  • Supports enabling/disabling and deleting resolutions
  • Supports Excel import/export with affected well type column

Related Requirement: REQ-KITCFG-006


Extractions Configurations

Extraction instrument configurations grouped by extraction model.

Data Elements:

ColumnDescription
Extraction ModelGrouping category for instruments
Instrument NameIndividual extraction instrument identifier

Design Notes:

  • Instruments grouped by extraction model in UI
  • Supports adding new models and instruments
  • Model names are editable
  • Instruments cannot be deleted (preserves data integrity)
  • Supports Excel import/export
  • All changes logged to audit trail

Related Requirement: REQ-KITCFG-003


Features Configurations

Feature visibility toggles controlling which application capabilities are available to users.

Data Elements:

ColumnDescriptionValues
Feature NameIdentifier for the featureSystem-defined
EnabledFeature availability statusBoolean
DescriptionPurpose of the featureFree text

Design Notes:

  • Part of Client Configuration category
  • Used to enable/disable optional functionality per client
  • Feature flags evaluated at runtime to show/hide UI elements and functionality

Related Requirement: REQ-CLIENTCFG-001


Help Items Configurations

Configuration for contextual help items and their associated tags.

Data Elements:

ColumnDescription
Help ItemHelp content identifier
TagsComma-separated list of associated tags
ContentHelp text content

Design Notes:

  • Tags displayed in help items table as comma-separated list
  • "No tags available for this help item" shown when no tags assigned
  • Supports Excel import/export of tags via kit configuration

Related Requirement: REQ-KITCFG-028


Known Quantities Configurations

Expected quantity values for control roles used in quantification by standard curve calculations.

Data Elements:

ColumnDescriptionValidation
RoleControl role identifierMust exist in Control Labels
MixThe assay mixRequired
TargetThe specific targetRequired
Known QuantityExpected quantity valuePositive numeric (rejects negative, zero, alpha, special chars, whitespace, empty)

Design Notes:

  • Used by quantification calculations for standard curve generation
  • Validates quantity values strictly to prevent data entry errors

Related Requirement: REQ-KITCFG-015


Lims Exports Configurations

Mappings between LIMS export codes and outcome messages for downstream integration.

Data Elements:

ColumnDescriptionValues
CodeUnique LIMS code identifierString
MessageAssociated outcome messageSupports dynamic terms: {LOQ}, {Quant}, {HIQ}
TypeMessage classificationExclude, Information, Warning
Causes Missing MixesTriggers missing mix statusBoolean
Is InhibitedMarks as inhibition-relatedBoolean
Does Prevent AnalyseBlocks further analysisBoolean

Design Notes:

  • Supports dynamic LIMS terms in messages for quantity reporting
  • Prompts for confirmation when closing with unsaved changes
  • Code values must be unique

Related Requirement: REQ-KITCFG-009


Mix and Targets Configurations

Core assay configuration defining mixes, their constituent targets, and analysis parameters.

Data Elements:

ColumnDescriptionValidation
Mix NameUnique identifier for the mixRequired for enabled mixes
TargetDNA/RNA sequence detectedPart of mix definition
DyeFluorescent dye usedPart of target definition
Internal Control (IC)Target used for extraction/amplification verificationBoolean, mutually exclusive with Passive
Passive TargetReference dye for normalizationBoolean, mutually exclusive with IC
Extraction InstrumentAssociated extraction modelOptional
CT Inhibition DeltaIC-specific CT thresholdPositive non-zero integer, default 3
Target Display OrderSorting order within mixNumeric, alphabetical if empty
Minimum FluorescenceMin RFU thresholdMax 16 integer + 16 decimal places
Expected ThresholdExpected CT valueMax 3 integer + 15 decimal places
Max FluorescenceMax RFU thresholdMax 16 integer + 16 decimal places, >= Min Fluorescence
EnabledMix availability statusBoolean

Design Notes:

  • Mix uniqueness determined by unique set of target/dye combinations
  • Unknown mixes auto-created when imported targets don't match any configured mix
  • Disabled mixes retain configuration settings but excluded from dropdowns
  • Sorting: enabled mixes first (alphabetical), then disabled (alphabetical)
  • Targets sorted alphabetically with IC penultimate, passive last

Related Requirement: REQ-KITCFG-001


QIR - Quantification Settings Configurations

Slope and intercept parameters used for quantification calculations.

Data Elements:

ColumnDescriptionValidation
TargetsTarget(s) using these settingsMulti-select
SlopeStandard curve slopeNon-nullable decimal (both or neither with Intercept)
InterceptStandard curve interceptNon-nullable decimal (both or neither with Slope)
MinSlopeMinimum acceptable slopeValidation bound
MaxSlopeMaximum acceptable slopeValidation bound
MinEfficiencyMinimum acceptable efficiencyValidation bound
MaxEfficiencyMaximum acceptable efficiencyValidation bound
MinR2Minimum R² valueValidation bound
MinControlsMinimum controls requiredInteger

Design Notes:

  • Slope and Intercept must be both filled or both empty
  • Import validates non-nullable decimal values
  • Supports moving targets between QIR setting rows

Related Requirement: REQ-KITCFG-018


Qualitative Reportings Configurations

Upper bound limits for quantitative groupings used by RQUANT, RQUAL, and RQUANTASQUAL reporting rules.

Data Elements:

ColumnDescriptionValues
MixThe assay mixRequired
TargetsTarget(s) for this reportingMulti-select
Specimen TypesApplicable specimen typesMulti-select
GroupReporting group number1-9 for RQUANT, 1 for RQUAL/RQUANTASQUAL
Group DescriptionDescription of the groupFree text
Upper BoundMaximum value for this groupNumeric

Design Notes:

  • Prevents duplicate reportings for same mix/target/specimen/group combination
  • Configured cut-offs used by reporting rules during evaluation
  • All changes logged to audit trail

Related Requirement: REQ-KITCFG-016


Rules Mapping Configurations

Assignment of analysis rules to specific observation types based on role, mix, target, and specimen type.

Data Elements:

ColumnDescriptionValues
Run OrderExecution sequenceInteger
RuleThe analysis ruleSystem-defined rule list
TypeRule categoryClassification type
RoleApplicable rolesMulti-select, includes "All"
MixApplicable mixesMulti-select, includes "All"
TargetApplicable targetsMulti-select, includes "All", "All non-IC"
Specimen TypeApplicable specimen types (if enabled)Multi-select

Design Notes:

  • Supports multi-select for role, mix, target, specimen type
  • "All" and "All non-IC" options available for target selection
  • Passive (reference) targets excluded from target selection
  • Unused rules (no assignments) can be hidden via toggle
  • Specimen type column only shown when use_sample_type config enabled

Related Requirement: REQ-KITCFG-024


Test Codes Configurations

Mappings between test codes on sample labels and specimen types.

Data Elements:

ColumnDescriptionValidation
Test CodeCode appearing on sample labelsUnique, required
MixAssociated assay mixRequired
Specimen TypeResulting specimen classificationExisting or new value

Design Notes:

  • Prevents duplicate test codes
  • Allows selecting existing specimen types or entering new ones
  • Used during run file import to classify samples

Related Requirement: REQ-KITCFG-017


Thermocyclers Configurations

Thermocycler instrument configurations grouped by thermocycler model.

Data Elements:

ColumnDescription
Thermocycler ModelGrouping category for instruments
Instrument NameIndividual thermocycler identifier

Design Notes:

  • Instruments grouped by thermocycler model in UI
  • Maintains default "Unknown" model and instrument entry
  • Instruments cannot be deleted (preserves data integrity)
  • Supports Excel import/export
  • Can optionally auto-populate entries from imported run file data (configurable via thermocycler_auto_populate setting)
  • JSON field mapping configurable via thermocycler_instrument_field setting

Related Requirement: REQ-KITCFG-004


Westgard Limits Configurations

Statistical control parameters (mean, standard deviation) for Westgard quality control rule evaluation.

Data Elements:

ColumnDescriptionValidation
MixThe assay mixRequired
TargetThe specific targetRequired
RoleThe control roleMust have valid control label mapping for mix
RangeWestgard range identifierSystem-generated
Start DateRange effective dateDate
Extraction ModelsApplicable extraction modelsMulti-select
InstrumentExtraction instrumentOptional
MeanStatistical mean for the rangeEditable only when no control data exists
SDStandard deviation for the rangeEditable only when no control data exists
Quant/CtMode selectorCT or Quantity
EnabledRange active statusBoolean slider

Design Notes:

  • Ranges with existing control data become display-only (except enabled slider)
  • Mean/SD changes reset Westgard failures on re-analysis if the failure was affected by the change
  • Import/export uses role name (not alias) - rows with aliases are ignored
  • Role selector shows only roles with valid control label mappings for selected mix
  • Disabled settings can be hidden via toggle (hide_disabled_westgard config)

Related Requirement: REQ-KITCFG-012


Dyes Configurations

Fluorescent dye definitions used in target detection.

Data Elements:

ColumnDescription
Dye NameUnique dye identifier
ColorDisplay color for the dye
WavelengthEmission wavelength

Design Notes:

  • Dyes are defined as part of the mix/target configuration
  • Each target within a mix is associated with a specific dye
  • Dye assignments determine which fluorescence channel is read during analysis

Related Requirement: REQ-KITCFG-001 (part of mix/target configuration)


Roles Configurations

Sample role definitions used for classifying wells during run file import.

Data Elements:

ColumnDescriptionValues
RoleRole identifierUnique name
TypeRole classificationPC (Positive Control), NC (Negative Control), Sample, Ignore, Quantitative
Is ExtractedExtraction control flagBoolean
LabelsMatching labels in run filesPipe-separated list, supports wildcards
MixAssociated mixRequired
Backup MixesFailover mixesOptional, pipe-separated
Resolution PriorityPriority for resolution matching (when enabled)Integer

Design Notes:

  • Roles are managed through Control Labels configuration
  • Wildcard patterns supported in label matching (case-insensitive)
  • Role aliasing and remapping supported
  • Can be excluded from IC delta check
  • Resolution priority column shown when use_role_priority_resolution config enabled

Related Requirement: REQ-KITCFG-007


Rules Configurations

Rule execution settings including error well handling and precedence order.

Data Elements:

ColumnDescriptionValues
RuleRule identifierSystem-defined
TypeRule categoryClassification type
Is Allow Error WellsExecute against wells with errorsBoolean
Precedence OrderExecution priority within typeInteger

Design Notes:

  • "Is Allow Error Wells" controls whether rule runs against error-flagged wells
  • Precedence changes automatically reorder affected rules within type category
  • Precedence changes take effect immediately for subsequent rule executions

Related Requirement: REQ-KITCFG-025


Westgard Events Configurations

Event codes and messages generated by Westgard rule violations.

Data Elements:

ColumnDescription
Event CodeUnique identifier for the Westgard event
MessageUser-facing description of the violation
RuleAssociated Westgard rule (1:2S, 1:3S, 2:2S, 7T, etc.)
SeverityEvent severity level

Design Notes:

  • Westgard events are generated when control measurements violate statistical boundaries
  • Events tied to specific Westgard rules (see sdd-algorithms.md for rule definitions)
  • Part of the overall Westgard quality control configuration

Related Requirement: REQ-KITCFG-012 (part of Westgard settings)


Specimens Configurations

Specimen type definitions used for sample classification and reporting.

Data Elements:

ColumnDescription
Specimen TypeUnique specimen identifier
DescriptionSpecimen type description

Design Notes:

  • Specimen types are used by:
    • Rule mappings (when use_sample_type enabled)
    • Reporting cut-offs (RQUANT, RQUAL, RQUANTASQUAL rules)
    • Test code mappings
  • Can be created via Test Codes configuration or directly
  • Specimen type filtering available in multiple configuration screens

Related Requirements:


The following SRS requirements are implemented by the design described in this document:

RequirementDomainDescriptionRelevance
REQ-CLIENTCFG-001Client ConfigurationView and Edit Client Configuration SettingsThis SDD documents the client configuration usage and categories that REQ-CLIENTCFG-001 manages
REQ-CLIENTCFG-002Client ConfigurationExport Client ConfigurationEnvironment variables and configuration data documented here support export functionality
REQ-CLIENTCFG-003Client ConfigurationImport Client ConfigurationConfiguration schema documented here defines importable settings
REQ-KITCFG-007Kit ConfigurationManage Control LabelsControl Labels Configurations section documents Excel schema and role mapping design
REQ-KITCFG-011Kit ConfigurationManage Combined Outcome RulesCombined Outcomes Excel schema section documents the configuration data format
REQ-KITCFG-012Kit ConfigurationManage Westgard SettingsWestgard Limits Configurations section documents Westgard parameter management
REQ-KITCFG-013Kit ConfigurationManage Cross Contamination LimitsCross Contamination Limits Configurations section documents this requirement
REQ-KITCFG-014Kit ConfigurationManage Curve Control LimitsCurve Control Limits Configurations section documents this requirement
REQ-KITCFG-019Kit ConfigurationManage Delta CT ConfigurationsDelta CT Configurations section documents this requirement
REQ-KITCFG-005Kit ConfigurationManage Error CodesError Codes Configurations section documents error code management
REQ-KITCFG-006Kit ConfigurationManage Error ResolutionsError Resolutions Configurations section documents resolution configuration
REQ-KITCFG-028Kit ConfigurationManage Help Item TagsHelp Items Configurations section documents help item management
REQ-CONFIGIO-004Config Import/ExportImport and Export Combined Outcomes ConfigurationCombined Outcomes Excel schema directly supports import/export validation
REQ-CONFIGIO-005Config Import/ExportImport and Export Control Labels ConfigurationControl Labels Excel schema directly supports import/export validation
REQ-CONFIGIO-011Config Import/ExportValidate Westgard Limits on ImportWestgard Limits Configurations section relates to import validation

Notes on Completed Sections

All configuration sections in this SDD have been populated from SRS requirements or SME input. The Alerts subsections were populated from REQ-REPORTS-013 and REQ-REPORTS-014 in the Reports SRS.