Clinical Consultations & Vitals
Relevant source files
The following files were used as context for generating this wiki page:
The Clinical Consultations & Vitals module provides the interface and backend logic for recording patient health metrics and provider clinical notes. The system facilitates the transition from patient check-in to consultation completion, ensuring clinical data is captured accurately, stored securely, and audited for compliance.
This module restricts clinical note-taking to Doctors while allowing both Front Desk staff and Doctors to record physiological vitals. It integrates with the Patient Chart to provide historical context during active consultations.
Clinical Workflow and Statuses
The application enforces specific appointment statuses for different clinical actions. Vitals recording is permitted as soon as an appointment is pending, but clinical notes require the patient to be checked_in.
The clinical workflow dictates that note-taking only begins after patient check-in.
Sources: apps/api/src/modules/clinical/service.ts:35-43, apps/api/src/modules/clinical/routes.ts:38-41
Vitals Management
The Vitals sub-module handles physiological measurements. The system automatically calculates BMI if both weight and height are provided. For female patients over 12 years old, the system includes a pregnancy status field.
Physiological Data Points
| Field | Type | Description |
|---|---|---|
bpSystolic | Integer | Systolic blood pressure (40–300 mmHg) |
bpDiastolic | Integer | Diastolic blood pressure (20–200 mmHg) |
pulse | Integer | Heart rate (20–250 bpm) |
temperatureC | Decimal | Body temperature in Celsius (30–45°C) |
spo2 | Integer | Oxygen saturation (50–100%) |
weightKg | Decimal | Weight in Kilograms (0.3–400kg) |
heightCm | Decimal | Height in Centimeters (20–250cm) |
painScore | Integer | Visual Analog Scale for pain (0–10) |
pregnancyStatus | Enum | 'not_pregnant', 'pregnant', or 'breastfeeding' |
Sources: packages/contracts/src/consultations.ts:114-124, apps/web/app/clinic/vitals-form.tsx:16-25
Data Persistence
When a user saves the vitals form, the client sends the entire set of fields. Any empty field in the form clears the corresponding reading in the database.
Sources: apps/api/src/modules/clinical/service.ts:203-219, apps/web/app/clinic/vitals-form.tsx:55-61
Consultation Notes
Consultation notes are stored as a single document per appointment. To prevent data loss in multi-tab environments, the system utilizes a revision counter for optimistic locking.
Consultation Note Components
| Component | Description |
|---|---|
| Chief Complaint | Primary reason for the visit (max 500 chars). |
| Symptoms | List of symptoms with duration. |
| Examination | Provider's objective findings (max 4000 chars). |
| Diagnoses | List of ICD-10 codes or free-text labels. |
| Plan | Treatment steps and next actions. |
| Private Notes | Notes visible only to doctors; never printed or shared. |
| Tests Advised | Investigations or lab work requested. |
| Advice | Patient-facing instructions. |
Sources: packages/contracts/src/consultations.ts:167-177, apps/api/src/modules/clinical/service.ts:98-106
Autosave and Revision Locking
The web interface implements a 1200ms "quiet time" debounced autosave. If a doctor attempts to save a version with a revision that does not match the database, the system rejects the update with a 409 Conflict, indicating a stale tab.
The sequence ensures concurrent edits do not overwrite clinical data.
Sources: apps/web/app/clinic/consultations/[id]/page.tsx:21-72, apps/api/src/modules/clinical/service.ts:257-285
Patient Chart
The Patient Chart provides a longitudinal view of clinical history, separate from the current visit's notes.
- Allergies: Tracks substances and reactions; includes a
sourcefield (doctor/patient). Patient-reported entries are labeled "unverified" until confirmed by a doctor. - Conditions: Tracks medical conditions, ideally utilizing ICD-10 codes.
- Medications: Tracks current medications and dosages.
- Recent Visits: Displays the last five completed visits, including chief complaints and diagnoses.
Chart entries are never physically deleted. When a user "removes" an entry, the system records the timestamp, the user ID, and a mandatory reason for removal.
Sources: packages/contracts/src/consultations.ts:5-87, apps/api/src/modules/clinical/service.ts:60-75, apps/api/src/modules/clinical/service.ts:161-175
Security and Compliance
Data Protection
- Encryption: Clinical notes are stored as encrypted ciphers in the database using a field-level cipher.
- Tenant Isolation: All clinical queries are wrapped in
withTenantto prevent cross-organisation data access. - Audit Logging: Every view and save operation (chart, vitals, consultation) triggers a
writeAuditentry recording the actor and the entity accessed. - Signature Locking: Once a prescription is signed, the
lockedAttimestamp is set. The backend rejects any furtherPUTrequests to vitals or consultation notes for that appointment.
Sources: apps/api/src/modules/clinical/service.ts:380-382, apps/api/src/modules/clinical/service.ts:388-403, apps/api/test/clinical.int.test.ts:153-162