Patient Pre-visit Workflow
Relevant source files
The following files were used as context for generating this wiki page:
The Patient Pre-visit Workflow is a standalone, patient-facing system designed to streamline the intake process through a calm, voice-first conversation flow. It leverages AI-powered Speech-to-Text (STT) and Text-to-Speech (TTS) to guide patients through identification, data intake, and check-in before they see a healthcare provider. Sources: patient-previsit-app/README.md:3-5, readmes/README_VOICE_VITALS.md:3-10
This workflow integrates directly with OpenMRS to load patient context and update clinical records. It primarily serves to reduce administrative friction in high-volume environments by allowing patients to self-report information, which is then structured for clinical use. Sources: patient-previsit-app/README.md:65-71, readmes/ARCHITECTURE_OVERVIEW.md
Core Workflow Phases
The pre-visit process is divided into four distinct phases to ensure data integrity and user engagement.
1. Identity Verification
Patients initiate the workflow by entering identifying information such as Patient ID, Date of Birth (DOB), and an optional appointment code. The backend verifies this identity against OpenMRS records. Sources: patient-previsit-app/README.md:46-52
2. Voice-First Intake
The intake process utilizes a guided conversation flow. The backend generates initial prompts and optional audio. Patients interact by tapping to record their responses, which are then processed via Sarvam STT. Sources: patient-previsit-app/README.md:54-63
3. Review and Structure
After the conversation, patients review a summary of the collected information. The system uses AI (Gemini API) to extract structured data—such as vitals—from the natural language transcripts. Sources: patient-previsit-app/README.md:50, readmes/FINAL_SUMMARY.md:120-135
4. Check-in and Wait
Once submitted, the patient is checked in via OpenMRS and placed in a digital queue, where they can see their current position. Sources: patient-previsit-app/README.md:51
System Architecture
The architecture consists of a React-based frontend and a FastAPI backend orchestration layer that communicates with both OpenMRS and AI services.
Logic Flow Diagram
The following diagram illustrates the sequence from audio capture to data storage in OpenMRS.
Backend Endpoints
The FastAPI backend facilitates the pre-visit lifecycle through specialized REST endpoints.
| Endpoint | Method | Description |
|---|---|---|
/previsit/verify | POST | Verifies patient identity using ID and DOB. |
/previsit/session | POST | Creates an intake session; auto-loads context from OpenMRS if needed. |
/previsit/chat | POST | Handles voice turns; returns next_question, audio_url, and collected_fields. |
/previsit/report/{id} | GET | Retrieves the generated summary for patient review. |
/previsit/report/{id}/submit | POST | Submits structured data to OpenMRS and checks in the patient. |
/previsit/status/{id} | GET | Provides the patient's current status and queue position. |
Sources: patient-previsit-app/README.md:73-80, patient-previsit-app/README.md:65-71
Voice Integration and UI Patterns
The application prioritizes a "calm efficiency" design, keeping transcripts and technical fallbacks secondary to the voice interaction.
- Interaction Model: Tap-to-toggle recording is the primary input method. Sources: patient-previsit-app/README.md:54-63
- Audio Playback: Backend-generated audio URLs are used for prompts to minimize client-side processing. Sources: patient-previsit-app/README.md:65-71
- Visual Hierarchy: Transcript visibility is restricted to a half-height conversation history drawer, while text fallbacks ("Type instead") remain hidden until required. Sources: patient-previsit-app/README.md:54-63
Vitals Extraction Logic
A key feature of the intake is the ability to extract clinical vitals from natural language. The system maps voice inputs to structured OpenMRS observations.
Unit Conversion and Mapping
The system automatically handles unit conversions relevant to the local clinical context.
| Metric | Source Unit | Target Unit |
|---|---|---|
| Temperature | Fahrenheit | Celsius |
| Weight | Pounds (lbs) | Kilograms (kg) |
| Height | Inches / Feet | Centimeters (cm) |
| Blood Pressure | Spoken "Over" | Systolic / Diastolic split |
Sources: readmes/FINAL_SUMMARY.md:120-135, openmrs-esm-patient-chart-main/packages/esm-patient-vitals-app/src/vitals/VOICE_VITALS_IMPLEMENTATION.md:270-285
Deployment and Configuration
The workflow requires specific environment variables to connect the frontend, backend, and AI providers.
| Variable | Description | Default Value |
|---|---|---|
VITE_OPENMRS_BASE_URL | OpenMRS REST API root | http://localhost:80/openmrs/ws/rest/v1 |
VITE_AI_API_URL | FastAPI orchestration URL | http://localhost:3001 |
VITE_VOICE_PROVIDER | STT/TTS service label | sarvam |
SARVAM_API_KEY | Backend key for STT | [Environment Defined] |
GEMINI_API_KEY | Backend key for NLP | [Environment Defined] |
Sources: patient-previsit-app/README.md:31-44, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:125-145
Summary
The Patient Pre-visit Workflow transforms unstructured patient voice input into structured medical data. By combining identity verification with an AI-guided intake session, the system ensures that by the time a patient meets a provider, their vitals and history are already populated within OpenMRS, thereby increasing clinical throughput and accuracy. Sources: patient-previsit-app/README.md:3-5, readmes/FINAL_SUMMARY.md:260-275