Pre-visit Backend Services
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Pre-visit Backend Services constitute a specialized orchestration layer designed to facilitate patient-facing intake workflows before clinical encounters. Within the OpenMRS ecosystem, these services bridge the gap between patient-facing prototypes and the core EHR backend, utilizing AI-driven tools for voice-first interactions, transcription, and identity verification. The system is built using FastAPI and integrates with cloud-based AI providers to automate data collection and clinical documentation.
Sources: patient-previsit-app/README.md, README.md:14-20
System Architecture and Orchestration
The pre-visit architecture is part of the broader "AI/ML Backend" which handles voice transcription and clinical extraction. It operates as a FastAPI service that orchestrates data flow between the patient-facing interface, Sarvam AI for speech-to-text (STT), and OpenMRS REST APIs.
Backend Component Relationships
The following diagram illustrates the relationship between the Pre-visit services and other system components:
This diagram shows the flow of patient data from the interface through the AI Backend to various cloud services and finally to the OpenMRS database.
Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:13-35, patient-previsit-app/README.md
Core API Endpoints
The pre-visit system exposes several endpoints for managing intake sessions, verifying identities, and processing conversational data.
| Endpoint | Method | Description |
|---|---|---|
/previsit/verify | POST | Verifies patient identity using ID, DOB, and optional appointment code. |
/previsit/session | POST | Creates an intake session; auto-loads context from OpenMRS if not provided. |
/previsit/chat | POST | Processes conversational turns; returns next question, audio URLs, and collected fields. |
/previsit/report/{id} | GET | Generates a pre-visit summary/report from collected data. |
/previsit/status/{id} | GET | Retrieves the current status of the intake session and queue position. |
Sources: patient-previsit-app/README.md:61-80
Conversational Logic and AI Integration
The backend manages a hybrid conversation flow where patient context is built from OpenMRS REST resources and optional FHIR resources. This context is used to generate personalized assistant turns.
Voice-First Interaction Flow
The interaction follows a structured sequence to ensure accurate data capture and high-quality user experience:
This sequence highlights the reliance on backend-generated audio URLs to prevent unnecessary TTS regeneration on the client side.
Sources: patient-previsit-app/README.md:46-59, readmes/FINAL_SUMMARY.md:124-142
Data Extraction and Mapping
A critical function of the pre-visit services is the transformation of unstructured transcription into structured medical observations. This is achieved through integration with modules like vitals_gemini_test.py and the medical documentation concept setup.
- Transcription Processing: The backend converts WebM audio to WAV format before routing to AI providers.
- Vitals Extraction: Structured JSON is returned for fields such as Temperature, BP, HR, and SpO2.
- Unit Conversion: The services perform automatic conversions (e.g., Fahrenheit to Celsius) to standardize data before saving to OpenMRS.
Sources: readmes/README_VOICE_VITALS.md:45-55, readmes/IMPLEMENTATION_SUMMARY.md:37-45
Configuration and Deployment
The pre-visit services are deployed as part of the ai-backend container. They require specific environment variables for cloud API authentication and OpenMRS connectivity.
Essential Configuration
SARVAM_API_KEY: Required for voice transcription and voice-first UI wiring.GEMINI_API_KEY: Used for OCR, vitals extraction, and clinical summarization.VITE_AI_API_URL: Points the frontend to the FastAPI orchestration layer (default port 3001).
Sources: AGENTS.md:15-20, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:118-135, patient-previsit-app/README.md:28-44
Summary
Pre-visit Backend Services enable an automated, voice-first patient intake process. By orchestrating interactions between Sarvam AI, Google Gemini, and OpenMRS, these services successfully transform natural patient speech into structured clinical data, significantly reducing the manual documentation burden for clinical staff while providing a guided experience for patients.