Quick Start Guide

Relevant source files

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

• AGENTS.md
• README.md
• readmes/VOICE_VITALS_QUICK_START.md
• readmes/FINAL_SUMMARY.md
• deployment/HOSPITAL-DEPLOYMENT-GUIDE.md
• readmes/IMPLEMENTATION_SUMMARY.md

This guide provides the necessary instructions to set up, configure, and verify the OpenMRS AI EHR system. The system integrates a traditional OpenMRS backend with modern AI-driven features, specifically focusing on voice-enabled vitals recording and automated clinical documentation.

The project is structured into three primary layers: the OpenMRS Backend (Java/Spring), the Frontend Microfrontends (React/TypeScript), and the AI/ML Backend (Python/FastAPI). This guide covers local development setup and the critical path for testing the Voice Vitals feature.

Sources: AGENTS.md:7-13, README.md:9-15

System Architecture and Data Flow

The system operates as a distributed network of services. The OpenMRS core handles patient data and clinical records, while specialized Python services provide AI capabilities like speech-to-text (STT) and natural language processing (NLP) for vital extraction.

High-Level Service Overview

The diagram above illustrates the end-to-end flow from voice recording to database persistence.
Sources: readmes/IMPLEMENTATION_SUMMARY.md:46-61, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:25-45

Prerequisites and Local Setup

Before starting the services, ensure your environment meets the following requirements:

• Docker Engine and Docker Compose v2.
• Python 3.10+ for FastAPI services.
• Node.js and Yarn 4.10.3 (Berry) for frontend development.

Service Initialization Sequence

1. Start OpenMRS Stack:
   Run the core backend services using Docker. On the first run, the backend may take approximately 2 minutes to initialize the database.

   docker compose -f o3-docker-compose/docker-compose.yml up -d
   

   Sources: AGENTS.md:17-18, README.md:104-106

2. Configure AI Backend:
   Navigate to openMRS-main, install dependencies from requirements.txt, and set up environment variables in a .env file.

   cd openMRS-main
   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   uvicorn main:app --host 0.0.0.0 --port 3001 --reload
   

   Sources: AGENTS.md:19, README.md:126-133

3. Start Gemini Proxy:
   In a separate terminal, start the proxy service required for LLM-backed summaries.

   uvicorn gemini_proxy:app --host 0.0.0.0 --port 8001 --reload
   

   Sources: README.md:141-143

4. Launch Frontend:
   Use the start:all command to ensure custom sidebar groups and medical documentation packages are loaded.

   cd openmrs-esm-patient-chart-main
   yarn start:all --backend http://localhost:80 --port 8010
   

   Sources: AGENTS.md:21, README.md:152-153

Configuration and Secrets

The AI features require valid API keys from Sarvam AI and Google Gemini. These must be configured in the openMRS-main/.env file.

Variable	Description	Source
SARVAM_API_KEY	Key for voice transcription (STT)	sarvam.ai
GEMINI_API_KEY	Key for vitals extraction and OCR	Google AI Studio
OPENMRS_API_URL	URL for the OpenMRS REST API	Local or Remote
OPENMRS_USERNAME	Admin username (Default: admin)	OpenMRS Admin
OPENMRS_PASSWORD	Admin password (Default: Admin123)	OpenMRS Admin

Sources: readmes/VOICE_VITALS_QUICK_START.md:9-16, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:118-124

Feature Guide: Voice Vitals Recording

The Voice Vitals feature allows clinical staff to record audio, which is then automatically transcribed and mapped to structured form fields in OpenMRS.

Interaction Sequence

The diagram depicts the synchronous and asynchronous steps involved in the AI extraction process.
Sources: readmes/FINAL_SUMMARY.md:73-90, readmes/IMPLEMENTATION_SUMMARY.md:46-61

Testing Procedure

To verify the Voice Vitals feature, follow these steps:

1. Navigate: Open a patient chart in the SPA (localhost:8010/openmrs/spa/) and click Record Vitals.
2. Record: Click "Start Recording" and speak test data (e.g., "Temperature 98.6 fahrenheit, BP 120 over 80").
3. Extract: Click "Stop Recording" followed by "Extract Vitals".
4. Verify: Ensure the temperature is converted to 37.0°C and BP is split correctly into systolic/diastolic fields.
5. Edit/Save: Modify a field manually to test form validation, then click "Save and close".

Sources: readmes/VOICE_VITALS_QUICK_START.md:25-56, readmes/IMPLEMENTATION_SUMMARY.md:144-154

Troubleshooting and Verification

If services fail to start or AI features behave unexpectedly, consult the following checks:

• Microphone Permissions: Ensure the browser has granted microphone access. Recording requires an HTTPS context or localhost.
• Backend Connectivity: Verify the AI backend is reachable by running curl http://localhost:3001/.
• API Status: Check the browser's Network tab for POST /transcribe_batch. A 500 error usually indicates an invalid SARVAM_API_KEY or GEMINI_API_KEY.
• OpenMRS Readiness: If the frontend redirects to a setup page, wait for the backend Docker container to finish its initialization (302 redirect → 200 OK on /session).

Sources: readmes/VOICE_VITALS_QUICK_START.md:58-81, AGENTS.md:27-28

Summary

This guide outlines the critical steps to deploy and test the OpenMRS AI EHR system. By following the service initialization sequence and ensuring environment variables are correctly set, developers and clinical staff can leverage AI-powered voice recording to streamline the capture of patient vitals and clinical documentation. Significant features include automated unit conversion, blood pressure parsing, and intelligent null handling to ensure form accuracy.

Sources: readmes/FINAL_SUMMARY.md:252-265, readmes/IMPLEMENTATION_SUMMARY.md:195-204