High-Level Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The OpenMRS AI-powered EHR system is a multi-layered platform designed to enhance clinical workflows through Voice-to-Vitals recording, automated transcription, and AI-driven data extraction. The architecture integrates a standard OpenMRS core with specialized AI backends and micro-frontends to support high-volume hospital environments.
The system is structured into four primary functional layers: the OpenMRS Backend (core clinical data), the Frontend Micro-frontends (O3 Patient Chart), the AI/ML Backend (transcription and NLP processing), and a standalone EHR Dashboard for consolidated patient overviews.
Sources: README.md:3-13, AGENTS.md:7-13, readmes/ARCHITECTURE_OVERVIEW.md
System Component Overview
The architecture is composed of several distinct services that communicate via REST APIs. The core clinical data resides in MariaDB, managed by the OpenMRS Java backend, while AI features are provided by specialized Python-based services.
Logical Service Layers
| Service | Technology | Role |
|---|---|---|
| OpenMRS Backend | Java/Spring, MariaDB | EHR REST API, clinical data storage, and user management. |
| AI Backend | Python, FastAPI | Voice transcription (Sarvam AI) and vitals extraction (Gemini). |
| Gemini Proxy | Python, FastAPI | LLM summarization and direct proxying for Gemini-backed services. |
| O3 Frontend | React, TypeScript | Micro-frontend architecture providing the patient chart and vitals recording UI. |
| EHR Dashboard | React, Vite | A consolidated dashboard for patient overviews and AI-generated summaries. |
| Gateway | Nginx | Reverse proxy handling routing for the OpenMRS Frontend and Backend. |
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:21-31, README.md:8-16, AGENTS.md:7-13
Architecture Diagram
The following diagram illustrates the connectivity between hospital network users, the internal services, and external AI cloud providers.
The diagram shows how the AI Backend acts as an orchestrator between the frontend interfaces and external LLM/STT providers while fetching context from the OpenMRS Backend.
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:36-47, readmes/IMPLEMENTATION_SUMMARY.md:120-135
Data Flow: Voice-to-Vitals Recording
One of the system's primary architectural features is the "Voice-to-Vitals" pipeline. This workflow spans the React frontend, the FastAPI AI backend, and external cloud services.
Sequence of Operations
- Audio Capture: The
useVitalsRecorderhook in the frontend captures audio via the Web Audio API. - Transcription: The audio blob is sent to the
/transcribe_batchendpoint. The AI Backend converts WebM to WAV and routes it to Sarvam AI. - NLP Extraction: The resulting text is passed to the
/process_vitals_transcriptionendpoint where the Gemini API extracts structured JSON. - Mapping: A frontend utility,
vitals-data.mapper.ts, transforms the AI JSON into a form schema, performing unit conversions (e.g., Fahrenheit to Celsius). - Persistence: The user reviews the auto-populated form in the
vitals-biometrics-formand saves it to the OpenMRS database via the standard REST API.
Sources: readmes/FINAL_SUMMARY.md:65-80, readmes/IMPLEMENTATION_SUMMARY.md:60-75, readmes/README_VOICE_VITALS.md:74-89
Voice Vitals Flowchart
Backend Architecture
The backend is bifurcated into the traditional OpenMRS stack and a modern FastAPI-based AI layer.
OpenMRS Backend Stack
The system utilizes a Dockerized OpenMRS 3.0 (O3) stack. It includes:
- MariaDB 10.11: Stores patient data, encounters, and observations.
- Java/Spring Backend: Provides the REST API used by all other components.
- Metadata Initializer: A Python-based one-shot container (
metadata-init) that ensures deterministic UUIDs for clinical concepts and encounter types upon first startup.
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:21-31, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:158-165
AI/ML Backend (Python/FastAPI)
The AI layer consists of two primary services:
- AI Backend (Port 3001): Handles heavy-duty tasks like audio file processing, interaction with Sarvam AI for Indian-accented speech-to-text, and vitals extraction.
- Gemini Proxy (Port 8001): A dedicated service for Gemini 2.5 Flash model interactions, focusing on medical documentation summarization and LLM proxying.
Sources: README.md:12-14, AGENTS.md:11-13, readmes/IMPLEMENTATION_SUMMARY.md:40-58
Frontend Micro-frontend Architecture
The frontend is built as a set of OpenMRS 3 micro-frontends (MFEs) using React 18 and TypeScript. These are managed within a monorepo using Turborepo and Yarn Berry.
Key Packages
- esm-patient-vitals-app: Contains the recording widget, the audio recording service, and the data mapping logic.
- esm-patient-medical-documentation-app: A custom package providing intake and assessment tabs.
- esm-patient-chart-app: The core application that hosts the various MFEs.
Sources: AGENTS.md:7-9, readmes/FINAL_SUMMARY.md:13-25, README.md:10
Component Relationship
The VitalsRecordingWidget is integrated into the vitals-biometrics-form.workspace.tsx. It provides a callback, handleVitalsExtracted, which uses the vitals-data.mapper.ts to update the React Hook Form state.
Sources: readmes/IMPLEMENTATION_SUMMARY.md:19-33, readmes/FINAL_SUMMARY.md:27-30
Network and Deployment Architecture
The system is deployed using Docker Compose, with persistent volumes for database data, OpenMRS application data, and AI recordings.
Network Isolation
| Port | Accessibility | Service |
|---|---|---|
| 80 | Hospital LAN | Nginx Gateway (Main UI Access) |
| 5175 | Hospital LAN | EHR Dashboard |
| 3001/8001 | Internal Only | AI Backend / Gemini Proxy |
| 3306 | Internal Only | MariaDB |
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:21-31, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:310-330
Conclusion
The High-Level Architecture of OpenMRS AI EHR provides a robust bridge between traditional clinical data management and modern AI capabilities. By separating the AI processing into dedicated FastAPI services and utilizing a micro-frontend approach, the system achieves a modular design that supports efficient, high-volume patient intake while maintaining the data integrity of the OpenMRS core.
Sources: readmes/ARCHITECTURE_OVERVIEW.md, readmes/FINAL_SUMMARY.md:200-215