Data Flow & Orchestration

Relevant source files

The following files were used as context for generating this wiki page:

• readmes/ARCHITECTURE_OVERVIEW.md
• readmes/FINAL_SUMMARY.md
• readmes/README_VOICE_VITALS.md
• readmes/IMPLEMENTATION_SUMMARY.md
• deployment/HOSPITAL-DEPLOYMENT-GUIDE.md
• readmes/DELIVERABLES.md
• openmrs-esm-patient-chart-main/packages/esm-patient-vitals-app/src/vitals/vitals-recording.service.ts

The Data Flow & Orchestration module in the OpenMRS AI EHR system manages the end-to-end lifecycle of clinical data captured via voice. It facilitates the movement of data from the user's microphone through transcription services, natural language processing (NLP) extraction, and finally into structured clinical forms within the OpenMRS ecosystem.

This system integrates the OpenMRS frontend (React), a FastAPI AI backend, and external cloud AI services (Sarvam AI and Google Gemini) to transform natural language into validated clinical observations. The orchestration ensures that unit conversions, data mapping, and form auto-population occur seamlessly while maintaining manual overrides for clinical safety.

Sources: readmes/ARCHITECTURE_OVERVIEW.md, readmes/IMPLEMENTATION_SUMMARY.md, README.md:10-25

## Voice-to-Structured-Data Pipeline

The core orchestration follows a multi-step pipeline that transitions through frontend capture, backend processing, and external AI service calls.

### Data Flow Stages

The pipeline is initiated when a clinician records patient vitals via the VitalsRecordingWidget. The resulting audio is handled as a blob and transmitted to the backend for conversion and transcription.

## Component Orchestration

The orchestration is distributed across frontend hooks, services, and backend endpoints.

### Frontend Service Layer

The vitals-recording.service.ts acts as the primary orchestrator on the client side. It manages the execution of the recordAndExtractVitals() method, which sequences the calls to the transcription and extraction endpoints.

Component	Responsibility	Relevant File
useVitalsRecorder	Manages microphone access and Web Audio API recording state.	useVitalsRecorder.ts
vitals-recording.service	Communicates with /transcribe_batch and /process_vitals_transcription.	vitals-recording.service.ts
vitals-data.mapper	Parses JSON output and handles Blood Pressure splitting (systolic/diastolic).	vitals-data.mapper.ts

Sources: readmes/DELIVERABLES.md, readmes/IMPLEMENTATION_SUMMARY.md, readmes/FINAL_SUMMARY.md

### Backend AI Processing

The FastAPI backend (main.py) orchestrates the interaction between the frontend requests and external AI models. It handles the conversion of audio formats (WebM to WAV) before sending data to Sarvam AI and integrates vitals_gemini_test.py for NLP extraction.

## Data Transformation & Mapping

A critical part of the orchestration is the transformation of natural language into medical-grade structured data.

### Unit Conversion and Parsing

The system performs automatic unit conversions during the extraction phase to ensure consistency in the OpenMRS database.

• Temperature: Fahrenheit to Celsius.
• Weight: Pounds (lbs) to Kilograms (kg).
• Height: Inches or Feet to Centimeters (cm).
• Blood Pressure: Splits "120 over 80" into discrete systolic and diastolic values.
• BMI: Automatically calculated from extracted weight and height.

Sources: readmes/FINAL_SUMMARY.md, readmes/README_VOICE_VITALS.md, readmes/IMPLEMENTATION_SUMMARY.md

### Intelligent Null Handling

The data mapper (vitals-data.mapper.ts) implements logic to ensure data integrity. If the AI model fails to extract a specific vital sign, the corresponding form field is left blank rather than being populated with a zero. This prevents incorrect clinical data from being saved and allows the user to manually enter the missing value.

Sources: readmes/README_VOICE_VITALS.md, readmes/IMPLEMENTATION_SUMMARY.md

## API Endpoint Specifications

The orchestration relies on specific backend endpoints to facilitate data flow.

Endpoint	Method	Input	Output
/transcribe_batch	POST	Audio Blob (Multipart/form-data)	Transcription Text (String)
/process_vitals_transcription	POST	Transcription Text (JSON)	Structured Vitals (JSON)

Sources: readmes/DELIVERABLES.md, readmes/IMPLEMENTATION_SUMMARY.md, openMRS-main/main.py

## Infrastructure Orchestration

The deployment architecture ensures these data flows remain internal where possible, only reaching out to cloud APIs for compute-heavy AI tasks.

## Summary

The Data Flow & Orchestration of the Voice Vitals feature is a coordinated effort between the React frontend, FastAPI backend, and cloud AI services. By sequencing Web Audio capture, format conversion, STT transcription, and NLP extraction, the system successfully automates the population of complex medical forms. The inclusion of intelligent mappers and manual review steps ensures that AI-driven automation remains clinically accurate and safe.

Sources: readmes/FINAL_SUMMARY.md, readmes/README_VOICE_VITALS.md