OpenMRS Proxy Client
Relevant source files
The following files were used as context for generating this wiki page:
The OpenMRS Proxy Client (implemented via the AI Backend and Gemini Proxy) serves as an intermediary layer between the frontend interfaces and the core OpenMRS REST API. Its primary purpose is to augment standard EHR workflows with AI-powered capabilities, such as voice transcription, OCR, and automated vitals extraction, while providing a simplified interface for the EHR Dashboard and Patient Chart applications.
This system acts as a specialized backend-for-frontend (BFF), handling complex orchestrations between third-party AI services (Sarvam AI, Google Gemini) and the OpenMRS data model. By centralizing these interactions, the Proxy Client ensures that sensitive clinical data is processed securely and mapped accurately to the specific medical concepts required by the hospital deployment.
Sources: README.md, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:23-38, readmes/ARCHITECTURE_OVERVIEW.md
System Architecture
The proxy architecture is split into two primary FastAPI services that handle different aspects of the clinical workflow: the AI Backend and the Gemini Proxy.
Service Overview
| Service | Technology | Internal Port | Primary Responsibility |
|---|---|---|---|
| AI Backend | Python / FastAPI | 3001 | Voice transcription, OCR, and vitals extraction. |
| Gemini Proxy | Python / FastAPI | 8001 | LLM summarization and structured medical data extraction. |
| Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:26-33, AGENTS.md:14-16 |
Data Flow Diagram
The following diagram illustrates how the Proxy Client interfaces between the user UI, cloud AI providers, and the OpenMRS core.
Core Functional Modules
1. Voice Vitals Processing
The Proxy Client implements a specialized pipeline for converting spoken vitals into structured clinical observations. It handles the lifecycle of an audio recording from the browser's Web Audio API through transcription and finally into OpenMRS concepts.
- Transcription: The client routes audio blobs to the
/transcribe_batchendpoint. Depending on audio length (under or over 30 seconds), it selects the appropriate Sarvam AI API path. - Extraction: Once transcribed, the text is sent to the
/process_vitals_transcriptionendpoint, which uses the Gemini API to identify 10 specific vital fields including Temperature, BP (systolic/diastolic), Heart Rate, and SpO2. - Unit Conversion: The proxy automatically normalizes units, such as Fahrenheit to Celsius or lbs to kg, before returning the data to the frontend.
Sources: readmes/ARCHITECTURE_OVERVIEW.md, openMRS-main/main.py, readmes/IMPLEMENTATION_SUMMARY.md:65-80
2. LLM Summarization Proxy
The gemini_proxy.py serves as a dedicated wrapper for the Google Gemini API, specifically tuned for medical summarization.
Endpoint:* /generate_summary
- Logic: The proxy constructs detailed medical prompts by combining patient demographics, current conditions, and recent encounters to ensure the LLM has sufficient context without the UI having to manage complex prompt engineering.
Sources: openmrs-esm-patient-chart-main/packages/esm-patient-chart-app/src/patient-summary/patient-summary.component.tsx:112-127, openMRS-main/gemini_proxy.py
Integration with OpenMRS
The Proxy Client relies on a strictly defined "UUID Contract" to interact with the OpenMRS database. It uses deterministic UUIDs for concepts, encounter types, and patient identifiers.
Required Metadata Configuration
The proxy services expect the following metadata to be present in the OpenMRS instance, often initialized by the metadata-init container:
| Metadata Type | Configuration File | Purpose |
|---|---|---|
| Concepts | medical_documentation_config.json | Mapping for 326 custom medical concepts. |
| Encounter Types | setup_medical_documentation_concepts.py | 27 types including "Chief Complaint" and "Vitals". |
| Attributes | setup_medical_documentation_concepts.py | Custom fields for Father Name and Occupation. |
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:144-165, openMRS-main/setup_medical_documentation_concepts.py:1-30
Configuration and Deployment
The proxy client services are deployed as Docker containers within a larger hospital stack.
Environment Variables
For the proxy to function, the following external API keys must be provided in the environment:
SARVAM_API_KEY: Required for voice-to-text features.GEMINI_API_KEY: Required for OCR and vitals extraction.OPENMRS_API_URL: The base URL of the OpenMRS REST instance (e.g.,http://backend:8080/openmrs/ws/rest/v1).
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:95-108, AGENTS.md:58-62
Summary
The OpenMRS Proxy Client is a critical architectural component that bridges the gap between modern AI capabilities and the robust but complex OpenMRS data model. By providing specific endpoints for voice, OCR, and summarization, it enables healthcare workers to capture patient data efficiently while ensuring the underlying EHR remains the single source of truth for structured medical records. This intermediary layer is essential for maintaining UI performance and simplifying the implementation of complex AI workflows.