Main FastAPI Backend
Relevant source files
The following files were used as context for generating this wiki page:
The Main FastAPI Backend serves as the AI-powered orchestration layer for the OpenMRS project. Its primary purpose is to provide endpoints for complex tasks that fall outside the standard OpenMRS clinical data storage, specifically voice-to-vitals transcription, Optical Character Recognition (OCR), and Natural Language Processing (NLP) for medical documentation. It acts as a bridge between the frontend Patient Chart and external AI services such as Sarvam AI and Google Gemini.
Sources: README.md:14-18, readmes/ARCHITECTURE_OVERVIEW.md
System Architecture and Integration
The backend is built using Python and FastAPI. It integrates with the OpenMRS Java/Spring backend via REST APIs and utilizes various third-party AI providers for specialized processing.
Data Flow for Voice Vitals
The following diagram illustrates the workflow when a clinician records patient vitals:
The system leverages a "batch" routing mechanism where recordings under 30 seconds use standard APIs and longer recordings utilize batch processing via Sarvam AI.
Sources: readmes/FINAL_SUMMARY.md, readmes/README_VOICE_VITALS.md, readmes/IMPLEMENTATION_SUMMARY.md
Core API Endpoints
The backend exposes several critical endpoints for AI-assisted clinical workflows:
| Endpoint | Method | Input | Purpose |
|---|---|---|---|
/transcribe_batch | POST | Audio Blob (WebM) | Transcribes audio to text using Sarvam AI. |
/process_vitals_transcription | POST | Transcription Text | Extracts structured vital signs using Gemini NLP. |
/generate_summary | POST | Patient Data Prompt | Generates a clinical summary (used by dashboard/proxy). |
/ | GET | N/A | Health check for the backend service. |
Sources: readmes/FINAL_SUMMARY.md, readmes/README_VOICE_VITALS.md, readmes/IMPLEMENTATION_SUMMARY.md, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md
Vitals Extraction Logic
The /process_vitals_transcription endpoint uses the vitals_gemini_test.py module to parse natural language. It is capable of extracting 10 distinct vital fields and performing automatic unit conversions.
| Field | Description | Unit Conversion |
|---|---|---|
| Temperature | Body temperature | Fahrenheit (°F) → Celsius (°C) |
| Weight | Patient weight | Pounds (lbs) → Kilograms (kg) |
| Height | Patient height | Inches (in) / Feet → Centimeters (cm) |
| Blood Pressure | Systolic/Diastolic | Parsed from "120 over 80" format |
| BMI | Body Mass Index | Auto-calculated from Ht/Wt |
Sources: readmes/README_VOICE_VITALS.md, readmes/IMPLEMENTATION_SUMMARY.md, readmes/FINAL_SUMMARY.md
Configuration and Environment
The backend requires several environment variables for authentication and external API access. These are typically managed via a .env file in the openMRS-main/ directory.
Required Environment Variables
| Variable | Purpose |
|---|---|
SARVAM_API_KEY | Authentication for Sarvam AI Speech-to-Text. |
GEMINI_API_KEY | Authentication for Google Gemini NLP/OCR. |
OPENMRS_API_URL | Base URL for the OpenMRS REST API (e.g., http://localhost:8080/openmrs/ws/rest/v1). |
OPENMRS_USERNAME | Credential for backend-to-OpenMRS communication. |
OPENMRS_PASSWORD | Credential for backend-to-OpenMRS communication. |
Sources: README.md:55-65, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md
Deployment and Monitoring
The backend is containerized for production environments. In the project structure, it is often deployed alongside a separate gemini_proxy.py service.
Service Stack Diagram
The backend service typically runs on port 3001 or 8000 depending on the environment configuration.
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md, README.md:14-22
Error Handling and Recovery
The FastAPI backend implements comprehensive error handling for several scenarios:
- Microphone/Audio Issues: Handled via specific status returns if audio format conversion fails.
- API Timeouts: Implements asynchronous processing to prevent blocking during long transcription or batch jobs.
- Missing Data: If vital signs are missing from a transcription, the backend returns
nullvalues, which the frontend mapper translates to blank fields rather than zeros to maintain data integrity.
Sources: readmes/FINAL_SUMMARY.md, readmes/IMPLEMENTATION_SUMMARY.md, readmes/README_VOICE_VITALS.md
The Main FastAPI Backend is a critical infrastructure component that enables AI-driven automation in OpenMRS. By offloading resource-intensive audio processing and NLP tasks to specialized cloud APIs while providing a unified REST interface for the frontend, it provides a scalable way to integrate modern AI features into clinical workflows.