Base Components

Encounter

An encounter is like a chapter in the patient's hospital story. It represents each time they interact with healthcare providers - whether it's a quick check at triage, a consultation with a doctor, or a surgical procedure.

Think of encounters as the "scenes" where medical care happens. Each encounter has a beginning and end time, involves specific healthcare providers, and takes place in a particular location within the hospital.

Data Model

Field	Type	Required	Description
patient_code	string	YES	Reference to the patient's unique code
visit_code	string	YES	Reference to visit the unique code
code	string	YES	Unique identifier for the encounter
class	string	YES	Class of encounter ("IPD", "OPD", or "EMERGENCY")
name	string	YES	What is the encounter (triage, ward names, sub-clinic … )
service_type	string	YES	Type of the service provided (nullable)
started_at	datetime	YES	Date and time encounter started
ended_at	datetime	YES	Date and time encounter ended (nullable)
encountered_by	string	YES	Name of healthcare provider
title	string	YES	Whether the healthcare provider is doctor or nurse
created_at	datetime	YES	Record creation timestamp
updated_at	datetime		Record the last update timestamp

Example

{
  "patient_code": "P25003877",  
  "visit_code": "V420650",  
  "code": "E317001",  
  "class_name": "OPD",  
  "name": "General Medicine",
  "service_type": "General Consultation",  
  "started_at": "2025-03-17T09:35:00.000+07:00",  
  "ended_at": "2025-03-17T10:15:00.000+07:00",  
  "encountered_by": "Dr. Chhun Sovannarith",
  "title": "Doctor",
  "created_at": "2025-03-17T09:35:00.000+07:00",  
  "updated_at": "2025-03-17T10:15:00.000+07:00"  
}

Observations

Observations are like detailed notes that healthcare providers write down about everything they notice, measure, or learn about a patient. Think of them as the "facts" collected during the patient's journey.

These could be anything from "Patient says they have a headache" to "Blood pressure is 120/80" to "Patient traveled to Mondulkiri province recently." Observations are incredibly flexible because healthcare involves collecting many different types of information.

Why are they flexible? Every patient is unique, and every hospital might track different things. Some might record detailed family history, others might focus on specific symptoms. The observation system adapts to capture whatever information is important for that patient's care.

Data Model

Field	Type	Required	Description
encounter_code	string	YES	Reference to encounter unique code
observation_code	string		Reference to parent observation (nullable)
name	string	YES	Name for the observation
category	string	YES	Name for the category of the observation if applicable
value	various	YES	Value of the observation (type depends on value_type)
value_type	string	YES	Type of value ("boolean", "string", "text", "integer", "float", "datetime", "time", "array", "complex")
value_unit	string		Unit of measurement (nullable)

Value Types - The Flexibility System

Since observations can be anything from a simple yes/no answer to complex medical data, we use different "value types" to handle this variety. Think of value types as different containers for different kinds of information.

Boolean (True/False) Example

"Does the patient smoke?"

{  
  "encounter_code": "EN20250317001",  
  "observation_code": null,  
  "name": "Smoker",  
  "category": "Social History",  
  "value": false,  
  "value_type": "boolean",  
  "value_unit": null  
}

String (Short Text) Example

"What's the patient's blood type?"

{  
  "encounter_code": "EN20250317001",  
  "observation_code": null,  
  "name": "Blood Type",  
  "category": "Laboratory",  
  "value": "O+",  
  "value_type": "string",  
  "value_unit": null  
}

Text (Long Description) Example

"What are the patient's symptoms and recent travel history?"

{  
  "encounter_code": "EN20250317001",  
  "observation_code": null,  
  "name": "Clinical Notes",  
  "category": "Assessment",  
  "value": "Patient reports symptoms of malaria including periodic fever, headache, and fatigue. Has history of travel to Mondulkiri province two weeks ago.",  
  "value_type": "text",  
  "value_unit": null  
}

Numeric Example

"What's the patient's blood glucose level?"

{  
  "encounter_code": "EN20250317001",  
  "observation_code": null,  
  "name": "Blood Glucose",  
  "category": "Vital Signs",  
  "value": 110,  
  "value_type": "integer",  
  "value_unit": "mg/dL"  
}

Array (List) Example

"What symptoms does the patient have?"

{  
  "encounter_code": "EN20250317001",  
  "observation_code": null,  
  "name": "Symptoms",  
  "category": "History",  
  "value": ["Fever", "Headache", "Fatigue", "Joint Pain"],  
  "value_type": "array",  
  "value_unit": null  
}

Complex (Structured Data) Example

"What's the patient's malaria risk assessment?"

{  
  "encounter_code": "EN20250317001",  
  "observation_code": null,  
  "name": "Malaria Risk Assessment",  
  "category": "Risk Assessment",  
  "value": {  
    "risk_level": "High",  
    "travel_history": true,  
    "prevention_measures": ["Bed nets", "Repellent"],  
    "endemic_area": "Mondulkiri province"  
  },  
  "value_type": "complex",  
  "value_unit": null  
}

TIP

Note: Medical history conditions use the same flexible structure as observations, but we've simplified them in the Medical History section to make implementation easier.

---

Conditions

Conditions represent medical diagnoses, health problems, or clinical states that affect a patient. Think of them as the "medical labels" that doctors assign to describe what's wrong with a patient or what health issues they're managing.

Unlike the simplified diagnosis component, conditions provide a more comprehensive way to track ongoing health issues, their severity, when they started, and their current status.

Data Model

Field	Type	Description
patient_code	string	Which patient this condition belongs to
visit_code	string	Which hospital visit this condition was identified during
encounter_code	string	Which encounter this condition was documented in
code	string	Unique identifier for this condition record
condition_code	string	Standard medical code for the condition (ICD-10, etc.)
condition_name	string	Human-readable name of the condition
category	string	Type of condition (primary, secondary, chronic, etc.)
severity	string	How serious the condition is (mild, moderate, severe)
status	string	Current state (active, resolved, inactive, etc.)
onset_date	date	When the condition first started
recorded_date	datetime	When this condition was documented
notes	text	Additional clinical notes about the condition
created_at	datetime	When this record was created
updated_at	datetime	When this record was last updated

Example

{
  "patient_code": "P25003877",
  "visit_code": "V420650",
  "encounter_code": "E317001",
  "code": "COND001",
  "condition_code": "E11.9",
  "condition_name": "Type 2 diabetes mellitus without complications",
  "category": "chronic",
  "severity": "moderate",
  "status": "active",
  "onset_date": "2020-05-15",
  "recorded_date": "2025-03-17T09:45:00.000+07:00",
  "notes": "Patient reports good glucose control with metformin",
  "created_at": "2025-03-17T09:45:00.000+07:00",
  "updated_at": "2025-03-17T09:45:00.000+07:00"
}

Services

Services represent the healthcare procedures, treatments, or interventions provided to a patient during their visit. Think of them as the "actions" that healthcare providers perform - from simple consultations to complex surgical procedures.

Services help track what was actually done for the patient, who performed it, when it happened, and often connect to billing and resource management systems.

Data Model

Field	Type	Required	Description
patient_code	string	YES	Which patient received this service
visit_code	string	YES	Which hospital visit this service was part of
encounter_code	string	YES	Which encounter this service was provided during
code	string	YES	Unique identifier for this service record
service_code	string	YES	Standard code for the service (CPT, local codes, etc.)
service_name	string	YES	Human-readable name of the service
category	string	YES	Type of service (consultation, procedure, diagnostic, etc.)
department	string	YES	Which hospital department provided the service
provider_name	string	YES	Name of the healthcare provider who performed the service
provider_title	string	YES	Role/title of the provider (Doctor, Nurse, Technician)
performed_at	datetime	YES	When the service was performed
duration_minutes	integer		How long the service took
quantity	integer	YES	How many units of this service were provided
unit_price	number	YES	Cost per unit of service
total_price	number	YES	Total cost for this service
status	string	YES	Service status (completed, cancelled, pending, etc.)
notes	text		Additional notes about the service
created_at	datetime	YES	When this record was created
updated_at	datetime		When this record was last updated

Example

{
  "patient_code": "P25003877",
  "visit_code": "V420650",
  "encounter_code": "E317001",
  "code": "SRV001",
  "service_code": "99213",
  "service_name": "Office visit for established patient",
  "category": "consultation",
  "department": "General Medicine",
  "provider_name": "Dr. Chhun Sovannarith",
  "provider_title": "Doctor",
  "performed_at": "2025-03-17T09:35:00.000+07:00",
  "duration_minutes": 30,
  "quantity": 1,
  "unit_price": 25000,
  "total_price": 25000,
  "status": "completed",
  "notes": "Routine follow-up for diabetes management",
  "created_at": "2025-03-17T09:35:00.000+07:00",
  "updated_at": "2025-03-17T10:05:00.000+07:00"
}

Service Categories

Category	Description	Examples
Consultation	Doctor visits and medical consultations	General consultation, specialist consultation
Diagnostic	Tests and examinations to diagnose conditions	Blood tests, X-rays, ultrasounds
Therapeutic	Treatments and interventions	Wound dressing, injections, physiotherapy
Surgical	Surgical procedures and operations	Minor surgery, major surgery, endoscopy
Emergency	Emergency care services	Emergency consultation, resuscitation
Administrative	Non-clinical services	Registration, medical certificates

---