Custom Medical Documentation

Relevant source files

The following files were used as context for generating this wiki page:

• openmrs-esm-patient-chart-main/packages/esm-patient-medical-documentation-app/README.md
• readmes/OPENMRS_FIELDS_PROFORMA.md
• openMRS-main/setup_medical_documentation_concepts.py
• openmrs-esm-patient-chart-main/packages/esm-patient-medical-documentation-app/src/discharge-summary/discharge-summary-form.workspace.tsx
• readmes/IMPLEMENTATION_SUMMARY.md
• deployment/HOSPITAL-DEPLOYMENT-GUIDE.md

Custom Medical Documentation in OpenMRS provides a specialized set of documentation tabs and workspaces designed specifically for high-volume public hospital environments, such as OPD intake workflows in India. This system extends the standard OpenMRS Patient Chart with 15 specialized clinical tabs, ranging from Chief Complaint to complex Discharge Summaries. Sources: CLAUDE.md:5-10, openmrs-esm-patient-chart-main/packages/esm-patient-medical-documentation-app/README.md:15-30

The module utilizes a robust metadata architecture consisting of over 300 custom clinical concepts and nearly 30 unique encounter types to ensure standardized data capture across clinical systemic examinations, history taking, and inpatient progress notes. Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:115-120, openMRS-main/setup_medical_documentation_concepts.py:12-25

Architecture and Metadata Management

The system relies on a strictly defined metadata contract where clinical fields are mapped to specific OpenMRS Concepts and Encounter Types via deterministic UUIDs.

Metadata Initialization

A dedicated Python automation suite, setup_medical_documentation_concepts.py, is used to provision the OpenMRS instance with the required clinical infrastructure. This script handles the creation of:

• Encounter Types: Categorizes clinical events (e.g., "Chief Complaint", "Abdominal Examination").
• Concepts: Individual data points (e.g., "Hypertension (past history)", "Liver Consistency").
• Concept Sets: Logical groupings of observations for forms.
• Person Attribute Types: Non-clinical demographic data like "Father's Name" and "Occupation".

Sources: openMRS-main/setup_medical_documentation_concepts.py:14-40, deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:124-135

Data Storage Model

Documentation is stored using a standard OpenMRS hierarchical model:

1. Patient Identifiers/Attributes: Demographic info (CR Number, Father's Name) is stored directly on the Patient or Person record.
2. Encounters: Every form submission creates or updates an Encounter of a specific type.
3. Observations (Obs): Clinical data points are saved as Observations linked to the Encounter.

Sources: readmes/OPENMRS_FIELDS_PROFORMA.md:7-15

Clinical Documentation Tabs

The following table summarizes the primary clinical documentation modules provided:

Tab Name	Purpose	Storage Method
Demographics	Captures CR Number, Admission Number, and social context.	Identifiers & Person Attributes
Chief Complaint	Patient's main reason for the visit.	Encounter + Free-text Obs
BGH & HOPI	Background history and narrative of present illness.	Encounter + Free-text Obs
Examination	Systemic (Respiratory, CVS, CNS, MSK) and general exams.	Encounter + Structured/Free-text Obs
Daily Notes	Inpatient progress tracking (Day of Admission, Issues, Plan).	Encounter + Numeric/Text Obs
Discharge Summary	Comprehensive summary of hospital stay and follow-up.	Encounter + Complex Obs Set

Sources: readmes/OPENMRS_FIELDS_PROFORMA.md:18-185, openmrs-esm-patient-chart-main/packages/esm-patient-medical-documentation-app/README.md:15-30

Documentation Workflow

Clinical documentation follows a specific lifecycle from metadata initialization to the generation of patient documents.

Submission Flow

The documentation process typically requires an active patient visit. When a clinician fills a workspace (e.g., Discharge Summary), the system performs an openmrsFetch to either createEncounter or updateEncounter with an array of Observation payloads.

The workspace manages state using react-hook-form and validates data against Zod schemas before REST submission. Sources: openmrs-esm-patient-chart-main/packages/esm-patient-medical-documentation-app/src/discharge-summary/discharge-summary-form.workspace.tsx:45-75, readmes/OPENMRS_FIELDS_PROFORMA.md:11-13

Specialized Workspaces: Discharge Summary

The Discharge Summary workspace is a high-complexity component featuring:

• AI Auto-fill: Aggregates data from Chief Complaint, Diagnosis, and Daily Notes to generate a clinical narrative.
• Medication Management: Uses useFieldArray to manage dynamic lists of discharge medications.
• PDF Generation: Utilizes jsPDF to generate professional, branded hospital documents directly in the browser.

Sources: openmrs-esm-patient-chart-main/packages/esm-patient-medical-documentation-app/src/discharge-summary/discharge-summary-form.workspace.tsx:100-140, openmrs-esm-patient-chart-main/packages/esm-patient-medical-documentation-app/src/discharge-summary/discharge-summary-form.workspace.tsx:142-180

Implementation Details

Metadata Configuration

Metadata is managed via a master configuration file, medical_documentation_config.json, which maps human-readable names to UUIDs used by the frontend components.

{
  "encounterTypes": {
    "Discharge Summary": "67246535-7151-4039-9946-f94d3065668b"
  },
  "concepts": {
    "Treatment Provided": "162165AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "Discharge Condition": "159640AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
  }
}

Sources: openMRS-main/setup_medical_documentation_concepts.py:650-680, openmrs-esm-patient-chart-main/packages/esm-patient-medical-documentation-app/README.md:5-12

Technical Requirements

The frontend documentation app is built as a microfrontend package within the OpenMRS 3.0 (O3) framework.

• Framework: React 18, TypeScript.
• Styling: Carbon Design System, Tailwind CSS.
• State Management: SWR (fetching), React Hook Form (forms).
• Data Validation: Zod.

Sources: CLAUDE.md:25-30, openmrs-esm-patient-chart-main/packages/esm-patient-medical-documentation-app/src/discharge-summary/discharge-summary-form.workspace.tsx:5-15

Summary

Custom Medical Documentation provides a specialized clinical layer atop OpenMRS, optimized for rapid data entry and comprehensive inpatient/outpatient tracking. Through automated metadata provisioning and intelligent workspaces like the Discharge Summary, it facilitates standardized clinical recording while enabling the generation of professional medical outputs. Sources: deployment/HOSPITAL-DEPLOYMENT-GUIDE.md:115-125, readmes/IMPLEMENTATION_SUMMARY.md:10-30