Rules Engine Framework
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Infrastructure requirements for rule execution, sequencing, and error handling during PCR analysis Domain: RULES-ENGINE
Statement
The system shall orchestrate the execution of PCR analysis rules, controlling which rules apply to a given analysis context, the sequence in which they execute, and how errors and warnings affect analysis flow.
The Rules Engine is the infrastructure layer that governs all rule execution. It does not define what individual rules calculate or validate; those are specified in separate rule documents. This framework ensures deterministic, configurable rule execution across all analysis contexts.
Quick Reference
| ID | Core Behavior | Priority | Status |
|---|---|---|---|
| REQ-RULES-ENGINE-001 | Executes rules only when valid mapping exists for current context | HIGH | Draft |
| REQ-RULES-ENGINE-002 | Executes rules in ascending order by configured run order | HIGH | Draft |
| REQ-RULES-ENGINE-003 | Stops or continues analysis based on error code configuration | HIGH | Draft |
Key Integration Points: Kit Configuration (rule mappings), Individual Rule Implementations, Analysis Pipeline
Rule Execution Flowchart (Illustrative)
This diagram illustrates the high-level rule execution flow. It does not specify UI layout, configuration interfaces, or internal rule algorithms.
Definitions
| Term | Definition |
|---|---|
| Rule | A discrete analysis algorithm that evaluates PCR data and returns a result or error code |
| Rules Mapping | Configuration that relates a rule ID to a combination of Dye, Target Name, Mix, and optionally Sample Type |
| Rule Setup | Configuration that defines the execution order for rules |
| Error Codes | Configuration that defines behavior for each possible error/warning code |
| Does prevent Analyse | A per-error-code flag determining whether the error stops analysis |
Rule Categories (Illustrative)
The following diagram shows how individual rules are organized by function. Each rule has its own detailed specification document.
Requirements
Rule Execution Control (REQ-RULES-ENGINE-001)
FR-ENGINE-001: Conditional Rule Execution Based on Mapping
The system shall execute a rule only when a valid mapping exists in the Rules Mapping configuration for the current analysis context.
Acceptance Criteria
Mapping Evaluation:
- Execute a rule only when the Rules Mapping contains an entry matching the rule ID to the current Dye, Target Name, and Mix
- Evaluate mappings before attempting rule execution
- Skip rules that have no matching mapping entry for the current context
Sample Type Filtering:
- When Sample Type filtering is enabled, require the mapping to also match the current Sample Type
- When Sample Type filtering is disabled, evaluate only Dye, Target Name, and Mix for rule mapping
Error Handling
- No rules mapped for analysis context: Complete analysis without executing any rules
- Rules Mapping configuration unavailable: Halt analysis and report configuration error
Trace: Source: 3.0.0-Rules (Row 1) | Jira: BT-674 | Tests: See scenarios
Sequential Execution (REQ-RULES-ENGINE-002)
FR-ENGINE-002: Sequential Rule Execution Order
The system shall execute rules in ascending order based on the numeric run order defined in the Rule Setup configuration.
Acceptance Criteria
Ordering:
- Execute rules in ascending order based on run order value from Rule Setup
- A rule with order value N shall complete before any rule with order value greater than N begins
- The execution sequence shall be deterministic for any given Rule Setup configuration
Error Handling
- Duplicate order values: Execute rules with same order value in a deterministic (implementation-defined) sequence
- Rule Setup configuration unavailable: Halt analysis and report configuration error
Trace: Source: 3.0.0-Rules (Row 2) | Jira: BT-674 | Tests: See scenarios
Error and Warning Handling (REQ-RULES-ENGINE-003)
FR-ENGINE-003: Error/Warning Flow Control
The system shall handle rule errors and warnings by stopping or continuing analysis based on the "Does prevent Analyse" configuration for each error code.
Acceptance Criteria
Blocking Errors:
- When a rule returns an error code where "Does prevent Analyse" is true, stop analysis immediately
- When analysis stops, return the error/warning code and message
- Interpret "Does prevent Analyse" as true when the configuration value is 'x'
Non-Blocking Errors:
- When a rule returns an error code where "Does prevent Analyse" is false, continue executing subsequent rules
- Apply the "Does prevent Analyse" logic to any subsequent errors encountered during continued analysis
- When analysis completes without blocking errors, return the first non-blocking error/warning encountered
- Interpret "Does prevent Analyse" as false when the configuration value is empty string ''
Uniform Treatment:
- Apply identical logic to warnings as to errors
Error Handling
- Error code not found in Error Codes configuration: Treat as blocking error and stop analysis
- Error Codes configuration unavailable: Halt analysis and report configuration error
Trace: Source: 3.0.0-Rules (Row 3) | Jira: BT-674 | Tests: See scenarios
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
| sample_type_filtering_enabled | [Client-specific] | When enabled, rule mappings must match Sample Type in addition to Dye, Target Name, and Mix | REQ-RULES-ENGINE-001 |
Assumptions
- At least one rule is configured and mapped before analysis is attempted
- Rule Setup tab contains valid numeric order values for all mapped rules
- Error Codes tab contains entries for all error codes that rules may return
- Client configuration determines whether Sample Type filtering is enabled
Individual Rule Specifications
Each rule listed below has its own specification document with detailed requirements, acceptance criteria, and tests.
Signal Quality Rules
| Rule | Document | Description |
|---|---|---|
| THRESHOLD | rule-threshold.md | Validates runfile threshold values against expected configuration |
| MANUAL_BASELINE | rule-baseline-check.md | Detects when manual baseline intervention is required |
| MINIMUM_FLUORESCENCE | rule-minimum-fluorescence.md | Validates minimum fluorescence thresholds |
| DOWNWARD_SIGMOID | rule-downward-sigmoid.md | Detects downward sigmoid curve patterns |
| DOWNWARD_SIGMOID_CONTROL | rule-downward-sigmoid-control.md | Applies downward sigmoid checks to control wells |
| NEGATIVE_SIGMOID | rule-negative-sigmoid.md | Detects negative sigmoid curve patterns |
| NEGATIVE_SIGMOID_CONTROL | rule-negative-sigmoid-control.md | Applies negative sigmoid checks to control wells |
| POSITIVE_SIGMOID | rule-positive-sigmoid.md | Detects positive sigmoid curve patterns |
| POSITIVE_SIGMOID_CONTROL | rule-positive-sigmoid-control.md | Applies positive sigmoid checks to control wells |
| UNEXPECTED_FL | rule-unexpected-fl.md | Detects unexpected fluorescence patterns |
Control Validation Rules
| Rule | Document | Description |
|---|---|---|
| NEC | rule-nec.md | Validates Negative Extraction Controls |
| BPEC | rule-bpec.md | Validates BioProduct Extraction Controls |
| CC | rule-cc.md | Validates Control Charts |
| CONTROL_FAIL | rule-control-fail.md | Handles control failures |
| MINCONTROLS | rule-mincontrols.md | Validates minimum control counts |
| EXTRACTION_CONTROLS | rule-extraction-controls.md | Validates extraction controls |
| WESTGARDS | rule-westgards.md | Applies Westgard QC rules |
Inhibition Detection Rules
| Rule | Document | Description |
|---|---|---|
| INHIBITION_CT | rule-inhibition-ct.md | Detects inhibition via CT values |
| INHIBITION_QUALITATIVE | rule-inhibition-qualitative.md | Qualitative inhibition detection |
| INHIBITION_QUANTIFICATION | rule-inhibition-quantification.md | Quantitative inhibition detection |
| INHIBITION_SERUM_QUANTITATIVE | rule-inhibition-serum-quantitative.md | Serum-specific quantitative inhibition |
| SYSTEMIC_INHIBITION | rule-systemic-inhibition.md | Detects systemic inhibition patterns |
| NEGATIVE_CONTROL_INHIBITION | rule-negative-control-inhibition.md | Inhibition in negative controls |
| IC_QUAL_SERUM | rule-ic-qual-serum.md | IC qualification for serum samples |
| ICCT | rule-icct.md | Internal Control CT validation |
Classification and Discrepancy Rules
| Rule | Document | Description |
|---|---|---|
| WDCLS | rule-wdcls.md | Well classification discrepancy detection |
| WDCLSC | rule-wdclsc.md | Well classification discrepancy (controls) |
| WDCLS_INVERT_SIGMOID | rule-wdcls-invert-sigmoid.md | Classification with inverted sigmoid |
| WDCLSC_INVERT_SIGMOID | rule-wdclsc-invert-sigmoid.md | Classification (controls) with inverted sigmoid |
| WDCT | rule-wdct.md | Well CT discrepancy detection |
| WDCTC | rule-wdctc.md | Well CT discrepancy (controls) |
| AMB | rule-amb.md | Ambiguous result handling |
| ADJ | rule-adj.md | Adjudication rule |
| ADJ_ZIKA | rule-adj-zika.md | Zika-specific adjudication |
| INDETERMINATE_CTS | rule-indeterminate-cts.md | Handles indeterminate CT values |
| MANAGING_INCONCLUSIVE | rule-managing-inconclusive.md | Manages inconclusive results |
Combined Outcome Rules
| Rule | Document | Description |
|---|---|---|
| COMBINED_OUTCOME | rule-combine-outcomes.md | Core combined outcome matching |
| SINGLE_WELL_COMBINED_OUTCOME | rule-single-well-combined-outcome.md | Single-well outcome evaluation |
| MULTIPLE_WELLS_COMBINED_OUTCOME | rule-multiple-wells-combined-outcome.md | Multi-well outcome evaluation |
| COMBINED_OUTCOMES_CONTROL | rule-combined-outcomes-control.md | Combined outcomes for controls |
| MIXES_MISSING | rule-mixes-missing.md | Detects missing mix conditions |
Quantification Rules
| Rule | Document | Description |
|---|---|---|
| RQUANT | rule-rquant.md | Reportable quantity calculation |
| MANAGING_QUANTITIES | rule-managing-quantities.md | Quantity management rules |
| QUANTITY_WEIGHT | rule-quantity-weight.md | Weighted quantity calculations |
| QUANT_VALIDATION | rule-quant-validation.md | Quantity validation |
| STDQT | rule-stdqt.md | Standard quantity determination |
| NOTTS_QUANT_MULTIPLY | rule-notts-quant-multiply.md | Nottingham quantity multiplier |
| STANDARD_CURVE_VALIDATION | rule-standard-curve-validation.md | Standard curve validation |
| LINEAR_REGRESSION_VALIDATION | rule-linear-regression-validation.md | Linear regression validation |
| QSSC | rule-qssc.md | Quantification standard sample check |
Reporting Rules
| Rule | Document | Description |
|---|---|---|
| RRESOLUTION | rule-rresolution.md | Report resolution rule |
| RWAC | rule-rwac.md | Report with acceptance criteria |
| REPORTING_QUAL | rule-reporting-qual.md | Qualitative reporting |
| REPORTING_QUANT_AS_QUAL | rule-reporting-quant-as-qual.md | Report quantitative as qualitative |
| REPEAT_SAMPLE | rule-repeat-sample.md | Repeat sample handling |
| CT_CUTOFF_WFINALCLS | rule-ct-cutoff-wfinalcls.md | CT cutoff with final classification |
Other Rules
| Rule | Document | Description |
|---|---|---|
| rule-wc.md | ||
| WT | rule-wt.md | Well target rule |
| WCAF | rule-wcaf.md | Well classification after final |
| DELTA_CT | rule-delta-ct.md | Delta CT calculation |
UI Notes (Illustrative)
Rule Configuration Interfaces
- Rules Mapping tab: Interface for configuring rule-to-context mappings (Dye, Target Name, Mix, Sample Type)
- Rule Setup tab: Interface for configuring rule execution order
- Error Codes tab: Interface for configuring error code behaviors including "Does prevent Analyse" flag
Implementation (Illustrative)
| Component | Location |
|---|---|
| Rule Model | Rule.php |
| Rules Controller | Http/Controllers/RulesController |
| Rule Base Interface | Analyzer/Contracts/AnalyzerRuleContract |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-RULES-ENGINE-001 | Conditional Rule Execution Based on Mapping | Test | Rule, RulesController | [Pending] | Draft |
| REQ-RULES-ENGINE-002 | Sequential Rule Execution Order | Test | Rule.execute() | [Pending] | Draft |
| REQ-RULES-ENGINE-003 | Error/Warning Flow Control | Test | Rule.execute() | [Pending] | Draft |
Notes
- This domain defines Rules Engine infrastructure, not individual rule implementations
- Individual rules are separate requirements documented in their respective domains (linked above)
- The Rules Engine executes rules but does not define what each rule calculates or validates
Acceptance Tests
Test: REQ-RULES-ENGINE-001
Test: Rule executes when mapping exists
Given: A rule "RuleA" is mapped to Dye "FAM", Target "COVID", Mix "Mix1"
And: Analysis is requested for Dye "FAM", Target "COVID", Mix "Mix1"
When: The Rules Engine processes the analysis
Then: "RuleA" shall execute
Test: Rule skipped when no mapping exists
Given: A rule "RuleA" is mapped to Dye "FAM", Target "COVID", Mix "Mix1"
And: Analysis is requested for Dye "HEX", Target "COVID", Mix "Mix1"
When: The Rules Engine processes the analysis
Then: "RuleA" shall not execute
Test: Sample Type filtering when enabled
Given: Sample Type filtering is enabled
And: A rule "RuleA" is mapped to Dye "FAM", Target "COVID", Mix "Mix1", Sample Type "Serum"
And: Analysis is requested for Dye "FAM", Target "COVID", Mix "Mix1", Sample Type "Plasma"
When: The Rules Engine processes the analysis
Then: "RuleA" shall not execute
Test: REQ-RULES-ENGINE-002
Test: Rules execute in ascending order
Given: "RuleA" has run order 10
And: "RuleB" has run order 5
And: "RuleC" has run order 15
And: All rules are mapped to the current analysis context
When: The Rules Engine processes the analysis
Then: Rules shall execute in order: RuleB, RuleA, RuleC
Test: REQ-RULES-ENGINE-003
Test: Blocking error stops analysis
Given: Error code "E001" has "Does prevent Analyse" = true
And: "RuleA" (order 1) returns error code "E001"
And: "RuleB" (order 2) is mapped to the analysis context
When: The Rules Engine processes the analysis
Then: Analysis shall stop after "RuleA"
And: "RuleB" shall not execute
And: Error code "E001" shall be returned
Test: Non-blocking error allows continuation
Given: Error code "E002" has "Does prevent Analyse" = false
And: "RuleA" (order 1) returns error code "E002"
And: "RuleB" (order 2) completes successfully
When: The Rules Engine processes the analysis
Then: Both "RuleA" and "RuleB" shall execute
And: Error code "E002" shall be returned
Test: First non-blocking error returned after successful completion
Given: Error code "E002" has "Does prevent Analyse" = false
And: Error code "E003" has "Does prevent Analyse" = false
And: "RuleA" (order 1) returns error code "E002"
And: "RuleB" (order 2) returns error code "E003"
When: The Rules Engine processes the analysis
Then: Error code "E002" shall be returned (first encountered)
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| SDD Algorithms | Running Rules Architecture, Rule Mapping Architecture, Complex Functionality - Rules Engine |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion)
- UI details are fully demoted to Illustrative section
- Configuration options are not encoded as requirements
- Acceptance criteria describe behavior, not UI mechanics
- Every requirement has acceptance criteria and source traceability
- Error handling addressed for I/O, validation, and external system requirements
- Open questions documented with owners assigned
- Consolidations documented in Reviewer Notes with reversibility info
- Module can survive a full UI redesign unchanged
- Refinements folded into Acceptance Criteria
- Traceability matrix is complete
Reviewer Notes
No consolidation was performed. All three source items represent distinct, independently testable framework capabilities:
| Requirement | Capability | Justification |
|---|---|---|
| REQ-RULES-ENGINE-001 | Rule mapping | Conditional execution based on context matching |
| REQ-RULES-ENGINE-002 | Rule ordering | Deterministic execution sequence |
| REQ-RULES-ENGINE-003 | Error handling | Flow control based on error severity |
These are infrastructure requirements that govern ALL rule execution, not variants of a single capability.
Reversibility: Source requirements preserved 1:1 from 3.0.0-Rules (Rows 1-3).