Product EngineeringFeaturesMachine Flags

Design Decisions

Key architectural choices, frontend/backend trade-offs, MongoDB storage strategy, and rendering decisions for Machine Flags.

👤 Mohammad Yameen📅 Updated: May 26, 2026🏷️ design🏷️ architecture🏷️ interfacing🏷️ machine-flags

Design Decisions

The Machine Flags feature was designed to support device-generated metadata alongside pathology parameter results across the complete interfacing pipeline.

The implementation spans:

  • Interfacing parsers
  • LIMS APIs
  • MongoDB-backed report storage
  • Report rendering
  • Device validation workflows

The architecture was intentionally designed to support highly variable device payloads while keeping frontend rendering reusable and scalable.

Device-Agnostic Parser Architecture

Machine Flags are parsed inside device-specific parser files located in the interfacing application.

Each device has its own parser implementation.

Examples:

  • Alinity
  • Siemens
  • Sysmex
  • Erba

Why

Different lab devices send:

  • Different protocols
  • Different HL7 structures
  • Different delimiters
  • Different flag formats
  • Different OBX segment mappings

A generic parser would become extremely complex and error-prone.

Design Choice

Use One Device → One Dedicated Parser Each parser converts raw device output into a normalized payload structure.

Benefit

  • Easy onboarding of new devices
  • Isolated device-specific logic
  • Easier debugging
  • Independent parser evolution

Trade-off

  • More parser files to maintain
  • Device-specific testing required

Normalized Payload Structure

All device parsers convert raw device output into a standardized payload.

Standard Payload

{
  "test_flags": [],
  "data": {
    "values": [
      {
        "testName": "",
        "value": "",
        "param_flags": []
      }
    ]
  }
}

Why

Lab devices generate highly inconsistent outputs.

The normalized structure provides:

  • Stable backend contracts
  • Reusable frontend rendering
  • Device-independent APIs

Separation of Test Flags and Parameter Flags

Machine Flags were intentionally divided into two independent categories.

Test-Level Flags

Stored in test_flags

Examples:

  • Hemolyzed
  • Review Needed
  • Clotted Sample

These represent sample-level or report-level observations.

Parameter-Level Flags

Stored in param_flags

Examples:

  • H
  • L
  • A++
  • Critical

These represent parameter-specific abnormalities.

Why

Some devices send:

  • Only test flags
  • Only parameter flags
  • Partial parameter flags
  • Both types simultaneously

A unified structure would create ambiguity during rendering.

Benefit

  • Cleaner rendering logic
  • Flexible device compatibility
  • Better UI separation

Partial Flag Support

The system was designed to support incomplete Machine Flag payloads.

Supported Scenarios

ScenarioSupported
Only test flags✅
Only parameter flags✅
Partial parameter flags✅
Mixed flags✅
No flags✅

Why

Different devices behave differently.

Some devices:

  • Do not send flags at all
  • Send flags only for abnormal parameters
  • Send sample-level warnings only

The architecture needed to tolerate incomplete payloads.

MongoDB-Based Report Storage

Machine Flag-enabled reports are stored in MongoDB-backed report documents.

Controlled By

enableDeviceFlags configuration.

Why MongoDB?

Traditional relational storage becomes inefficient for:

  • Highly dynamic parameter structures
  • Large interfaced reports
  • Device metadata
  • Nested flag arrays

MongoDB provides:

  • Flexible schemas
  • Easier nested storage
  • Faster document retrieval

Design Choice

Each parameter value is stored as an independent document-like object.

Example:

{
  "value": 110.12,
  "param_flags": ["P1", "H~N"],
  "test_flags": ["Review Needed"]
}

Benefit

  • Flexible report structure
  • Easier interfacing support
  • Simplified frontend rendering
  • Better extensibility

Trade-off

  • Additional MongoDB dependency
  • Dual storage architecture

Repeated Test Flags Across Parameters

test_flags are repeated across report parameter objects.

Example:

{
  "test_flags": ["Review Needed"]
}

exists on multiple parameter entries.

Why

This avoids:

  • Separate lookup structures
  • Additional joins
  • Complex frontend state synchronization

Frontend components can retrieve flags directly from any report value.

Trade-off

  • Small amount of duplicated data

Benefit

  • Simpler rendering logic
  • Faster UI access
  • Reduced transformation overhead

Reusable Frontend Rendering Pipeline

Machine Flags were integrated into the existing report rendering system instead of creating separate rendering modules.

Why

The report rendering system already handled:

  • Parameter rendering
  • PDF rendering
  • Report editing
  • Read-only preview

Adding Machine Flags into the same pipeline minimized duplication.

Design Choice

Reuse existing components:

  • EditReportView
  • ReadReportView
  • TestNameColumn
  • ReportRangeInput

Benefit

  • Shared UI logic
  • Consistent rendering
  • Easier maintenance
  • Faster implementation

Shared Rendering Across Multiple Screens

Machine Flags use the same rendering architecture in:

ScreenShared Components
Report EntryEditReportView / ReadReportView
OverviewEditReportView / ReadReportView
PDF PreviewReadReportView
Device ValidationShared renderers

Why

Users should see identical Machine Flag behaviour across all report workflows.

PDF Rendering Strategy

Machine Flags are rendered only inside interactive LIMS UI workflows.

Examples:

  • Report Entry
  • Overview Reports
  • Device Results Validation

PDF Preview Behaviour

Machine Flags are intentionally hidden when the user switches to PDF Preview Mode

Why

Machine Flags are considered operational review metadata intended primarily for internal validation workflows.

The PDF preview is treated as the final printable clinical report format.

To keep the printable report cleaner and clinically focused:

  • Machine Flags are excluded from PDF rendering
  • Internal validation metadata is hidden
  • Only finalized report content is displayed

Why

The final printable clinical report is treated as the authoritative reviewable format.

Showing flags in PDF mode ensures:

  • Clinical visibility
  • Print consistency
  • Review accuracy

Design Choice

Machine Flags are rendered only in frontend interactive workflows where users actively review interfaced results.

They are not included in:

  • PDF preview rendering
  • Printable report output

Benefit

  • Cleaner printable reports
  • Reduced PDF clutter
  • Better patient-facing readability
  • Separation between operational metadata and final report content

Trade-off

Users cannot view Machine Flags inside PDF preview mode.

To review Machine Flags, users must use:

  • Report Entry
  • Overview Reports
  • Device Results Validation

Device Result Validation Integration

Machine Flags were integrated into the Device Results Validation screen.

Why

Users validating interfaced results need visibility into:

  • Sample abnormalities
  • Parameter warnings
  • Device-generated alerts

before report approval.

Design Choice

Render:

  • Test flags in grouped rows
  • Parameter flags beside parameter names

Dynamic Rendering Instead of Hardcoded Flags

Frontend rendering treats Machine Flags as dynamic strings.

Example:

["H", "A++", "Review Needed"]

Why

Different devices generate different flag formats.

Hardcoding if flag === "H" would make onboarding new devices difficult.

Benefit

  • Fully device-agnostic rendering
  • No frontend dependency on device types
  • Future-proof implementation

Automated Result Awareness

Machine Flag-enabled results include automatedValue = 1

Why

Frontend workflows need to distinguish:

  • Device-generated results
  • Manual entries

This supports:

  • Validation workflows
  • Review flows
  • Approval logic

MongoDB Retrieval Strategy

Machine Flags are fetched together with report values.

Why

Avoid:

  • Separate flag APIs
  • Multiple frontend fetches
  • Additional synchronization logic

Benefit

  • Single-source report rendering
  • Reduced API calls
  • Faster report loading

Interfacing-Centric Architecture

Machine Flags processing primarily happens in the interfacing layer.

Why

The LIMS backend should remain device-agnostic.

The interfacing application acts as the translation layer between:

Device Protocols
        ↓
Normalized Payload
        ↓
LIMS APIs

Benefit

  • Cleaner backend APIs
  • Reduced backend parser complexity
  • Easier device onboarding

Extensibility Considerations

The architecture was designed to support future additions such as:

  • Device extra metadata
  • QC markers
  • Delta-check warnings
  • AI-generated interpretations
  • Instrument comments
  • Device images/graphs

without major schema redesign.

Failure-Tolerant Rendering

Frontend rendering was intentionally built to tolerate missing data.

Examples

Supported safely:

"param_flags": []
"test_flags": null
"param_flags": undefined

Why

Device payloads are often inconsistent across vendors.

Strict rendering assumptions would cause runtime failures.

Workflow Architecture

Patient Sample Collected
        │
        ▼
Sample Processed in Device
        │
        ▼
Device Generates Raw Output String
        │
        ▼
Interfacing Application Receives Raw Data
        │
        ▼
Device-Specific Parser Selected
        │
        ▼
Parser Extracts:
   ├── Parameter Values
   ├── Test Flags
   └── Parameter Flags
        │
        ▼
Normalized Payload Generated
        │
        ▼
Payload Sent to LIMS API
        │
        ▼
Data Partial API Processes Payload
        │
        ▼
Results + Flags Stored in MongoDB
        │
        ▼
Report Values Retrieved by APIs
   ├── getReportFormatForTestEntry()
   ├── getPatientAllReports()
   └── fetchDeviceResultsAPI()
        │
        ▼
Frontend Rendering Pipeline
   ├── Report Entry
   ├── Overview
   ├── PDF Preview
   └── Device Validation
        │
        ▼
Machine Flags Displayed to User

Frontend Rendering Flow

MongoDB Report Values
        │
        ▼
API Response
        │
        ▼
Report Value Objects
   ├── test_flags
   └── param_flags
        │
        ▼
Frontend Renderers
   ├── testFlagsRenderer
   ├── TestNameColumn
   ├── groupRowRenderer
   └── parameterNameCellRenderer
        │
        ▼
Machine Flags Visible in UI

Summary

The Machine Flags architecture was designed around:

  • Device variability
  • Flexible payload handling
  • MongoDB-backed report storage
  • Reusable frontend rendering
  • Device-agnostic parsing
  • Failure-tolerant rendering
  • Unified report workflows

The implementation prioritizes:

  • Scalability
  • Extensibility
  • Device compatibility
  • Reusable rendering
  • Clinical visibility
  • Simplified frontend integration

Backend

End-to-end backend flow for Machine Flags including device payload ingestion, report value persistence, and machine flag retrieval across LIMS modules.

Overview

High-level overview of the Microbiology feature: purpose, scope, and core concepts.

On this page

Design DecisionsDevice-Agnostic Parser ArchitectureWhyDesign ChoiceBenefitTrade-offNormalized Payload StructureStandard PayloadWhySeparation of Test Flags and Parameter FlagsTest-Level FlagsParameter-Level FlagsWhyBenefitPartial Flag SupportSupported ScenariosWhyMongoDB-Based Report StorageControlled ByWhy MongoDB?Design ChoiceBenefitTrade-offRepeated Test Flags Across ParametersWhyTrade-offBenefitReusable Frontend Rendering PipelineWhyDesign ChoiceBenefitShared Rendering Across Multiple ScreensWhyPDF Rendering StrategyPDF Preview BehaviourWhyWhyDesign ChoiceBenefitTrade-offDevice Result Validation IntegrationWhyDesign ChoiceDynamic Rendering Instead of Hardcoded FlagsWhyBenefitAutomated Result AwarenessWhyMongoDB Retrieval StrategyWhyBenefitInterfacing-Centric ArchitectureWhyBenefitExtensibility ConsiderationsFailure-Tolerant RenderingExamplesWhyWorkflow ArchitectureFrontend Rendering FlowSummary