01 / Problem
The clinical signal begins in natural language.
Nursing notes contain observations that matter to the care context, but spoken language is not automatically structured, coded, or ready to cross a system boundary. The engineering challenge is to preserve the statement, expose uncertainty, and give a clinician the final say.
- Vital signs and fluid intake
- Pain, symptoms, mobility and observations
- Nursing interventions and contextual qualifiers
02 / Architecture
A model proposes; approved data crosses a controlled contract.
The implementation separates local speech and language processing from a typed clinical extraction, grounding checks, review, and a versioned gateway contract. Vital Mapper does not write directly to HAPI FHIR; the monitoring system owns the authoritative FHIR, LOINC and UCUM mapping.
- 01Voice inputExplicit microphone action
- 02Encrypted audio storeProtected recording persistenceimplemented
- 03faster-whisperLocal speech-to-text serviceimplemented
- 04Ollama extractionLocal structured proposalimplemented
- 05Grounding + canonical modelUnsupported facts are rejected
- 06Human approvalCorrection before submission
- 07Interop gatewayMonitoring contract and FHIR boundaryimplemented
03 / Data flow
Human review is a gate, not a footnote.
The source transcript remains visible next to the extracted information and FHIR proposal. A nurse can confirm, correct, or reject every proposed element before any persistence step.
- 01Transcript
- 02Extracted information
- 03FHIR proposal
- 04Nurse review
- 05Confirm / correct / reject
- 06Persist through a controlled API
This case study models assistance, not autonomous clinical decision-making.
04 / Clinical data model
From an utterance to a grounded clinical model.
The implemented extraction keeps source-grounding and missing information visible. Intermediate structure lets laterality, mobility and measurement units be reviewed before the approved report and vital values are submitted to the monitoring contract.
“The patient has had pain in the right knee since this morning. Mobility is impaired. Temperature: 37.8 °C.”
- Symptom
- Knee pain
- Laterality
- Right
- Mobility
- Impaired
- Temperature
- 37.8 °C
After approval, the gateway forwards grounded vital values to Monitoring Pflege. That backend deterministically maps measurement types to an Observation; approved narrative is stored as a Composition with an active Encounter context.
{
"resourceType": "Observation",
"status": "preliminary",
"subject": { "reference": "Patient/synthetic-1042" },
"encounter": { "reference": "Encounter/synthetic-enc-37" },
"code": { "text": "Body temperature" },
"valueQuantity": {
"value": 37.8, "unit": "°C",
"system": "http://unitsofmeasure.org", "code": "Cel"
}
}05 / Interoperability
Interoperability is more than valid JSON.
FHIR resource choice depends on the documented fact, care workflow, local profiles and the receiving system. The model therefore proposes a typed clinical fact first; the mapper applies rules for the agreed integration contract.
Observation
Measurements and selected findings, with units and references.
Condition
May fit a clinically maintained problem, subject to workflow and governance.
ClinicalImpression
Can carry an assessment context where appropriate.
Composition
Can represent a structured document context when the implementation calls for it.
Provenance
Can record creation and review context without replacing the source note.
FHIR / terminologyTerminology is a separate semantic layer: UCUM can normalize units; LOINC and SNOMED CT are conceptual integration targets where a governed value set and licensing context exist. This case study does not claim a completed terminology service.
06 / Security
Privacy and trust boundaries are implemented in the path.
Vital Mapper uses a server-side OIDC BFF session, encrypted Redis-backed tokens, role- and patient-level checks, encrypted audio storage and audit logging. Local faster-whisper and Ollama services reduce external model data transfer in the development architecture.
Audio
Recordings are encrypted at rest; the frontend keeps audio out of browser persistent storage.
AI processing
faster-whisper and Ollama run as local/on-premises-capable services in the Compose architecture.
API access
Keycloak/OIDC, server-side sessions and RBAC protect API and patient access.
Integration
Approved data travels through the gateway; direct HAPI access is intentionally quarantined.
Implemented controls are not a certification or a claim of production clinical deployment.
07 / Engineering decisions
Key engineering decisions
- 01
Grounded extraction before integration
Unsupported values are rejected instead of being completed by the model.
- 02
Review before persistence
Every proposal remains editable clinical documentation, not an autonomous conclusion.
- 03
Gateway, not direct FHIR access
Vital Mapper sends approved information through a versioned gateway; Monitoring Pflege applies the authoritative FHIR mapping.
- Representing negation, uncertainty, timing and attribution without flattening the spoken statement.
- Choosing resource profiles and terminology bindings that fit the target workflow rather than a generic demo.
- Making corrections traceable without exposing unnecessary clinical content in logs.
08 / State & direction
Current state
IMPLEMENTED PROTOTYPEThe repository implements the React/FastAPI workflow, encrypted audio persistence, local faster-whisper transcription, Ollama extraction, grounding checks, manual approval, Keycloak/OIDC BFF sessions, PostgreSQL/Redis and the Monitoring gateway submission path.
FUTURE DIRECTION
Future direction
Next work is rigorous extraction evaluation, integration-contract testing across deployments, operational retention policy, and clinical validation/governance before any production care use.
09 / What this demonstrates
What this project demonstrates
- 01AI engineering with an explicit human-in-the-loop boundary
- 02Clinical data modelling before serialization
- 03FHIR-aware integration design and terminology humility
- 04Privacy-by-design thinking at system boundaries