@openmrs/esm-voice-navigation

OpenMRS 3.x micro-frontend that adds a voice-command mic button to the global top navbar and the patient chart header. Audio is sent to the sibling FastAPI backend (in ../backend/) which runs the ASR → NLU → entity → OpenMRS REST pipeline and returns a structured response the module uses to navigate the SPA.

Extensions registered

| Component | Slot | Where it appears | | -------------------- | ----------------------------------- | ----------------------------- | | voiceButton | top-nav-actions-slot | O3 top navbar (every page) | | voiceButtonPatient | patient-chart-header-right-slot | Patient chart header |

Each extension can be disabled individually via the config UI (enableInNavbar, enableInPatientChart).

Prerequisites

• Node 18+ and Yarn 1.x
• A running OpenMRS 3.x instance (the dev backend, e.g. http://localhost:9090/openmrs)
• The FastAPI voice backend running at the URL set by backendUrl (default: /voice, same-origin via reverse proxy)

Install & run (development)

cd openmrs-esm-voice-navigation
yarn install
yarn start --backend http://localhost:9090/openmrs

openmrs develop boots the O3 shell on http://localhost:8080/openmrs/spa with this module wired into the import map. The O3 shell proxies /openmrs/* to your real backend so login and patient data work.

Build & deploy (production)

yarn install
yarn build        # writes dist/openmrs-esm-voice-navigation-<hash>.js

Copy dist/ to a location served by your OpenMRS webapp (e.g. .../openmrs/WEB-INF/classes/frontend/voice-navigation/) or to any HTTP host (nginx, S3…). Then register it in the O3 import map. In the distro's spa-assemble-config.json:

{
  "frontendModules": {
    "@openmrs/esm-voice-navigation": "0.1.0"
  }
}

or in the running instance's import map:

{
  "@openmrs/esm-voice-navigation":
    "/openmrs/spa/voice-navigation/openmrs-esm-voice-navigation.js"
}

Config

Admins configure via O3's System Administration → Configuration UI, or via a JSON override file. Keys:

| Key | Default | Purpose | | ------------------------- | ---------- | ------------------------------------------------------------------------------ | | backendUrl | /openmrs/voice | FastAPI base. Default targets the Tomcat-Standalone proxy servlet; use /voice behind nginx/Apache, or a full URL for cross-origin dev. | | language | en | ASR hint language. en covers Nigerian English + Pidgin. | | enableInNavbar | true | Show mic in the global navbar. | | enableInPatientChart | true | Show mic in the patient chart header. | | maxRecordingSeconds | 15 | Auto-stop recording after this many seconds. |

How session forwarding works

The module issues fetch(..., { credentials: "include" }), so when the FastAPI backend is reverse-proxied on the same origin as OpenMRS, the browser's JSESSIONID cookie flows through to the backend, which then forwards it to OpenMRS. The backend therefore acts as the logged-in clinician (correct provider UUID, audit trail) with zero extra code.

In cross-origin development (backendUrl: http://localhost:8000/voice) the cookie is stripped by CORS; the backend falls back to the service account configured in its own .env. This is fine for development but not recommended for production.