Patient Management System
Relevant source files
The following files were used as context for generating this wiki page:
The Patient Management System manages the registration, demographic tracking, and categorization of patients within the digital healthcare platform. It provides specialized logic for Unique Health Identification (UHID) generation, duplicate record prevention, and family relationship mapping.
The system ensures that staff members, including front desk, doctors, and clinic admins, can efficiently manage patient records while maintaining data integrity across different organizations. It leverages Row-Level Security (RLS) to ensure that patient data remains isolated within the tenant's organization.
Sources: apps/api/src/modules/patients/service.ts:74-79, apps/api/src/modules/patients/routes.ts:25-30
Registration and UHID Management
The system allocates a Unique Health Identifier (UHID) to every patient during registration. A clinic admin configures the UHID numbering rules, including optional prefixes and starting numbers.
UHID Allocation Logic
The system uses a pessimistic locking mechanism to prevent race conditions during concurrent registrations. It starts at a default value of 10001 unless configured otherwise. If a generated UHID is already in use (e.g., from an import), the system increments the counter and retries until a unique ID is found.
Sources: apps/api/src/modules/patients/service.ts:333-356, apps/api/src/modules/patients/service.ts:26
The diagram shows the sequential process of generating and verifying a unique UHID under a database lock.
Sources: apps/api/src/modules/patients/service.ts:333-356
Configuration Parameters
| Parameter | Type | Description | Default |
|---|---|---|---|
prefix | string | Letters and digits (e.g., 'EK') | Empty |
nextNumber | integer | The numeric part of the next UHID | 10001 |
Sources: packages/contracts/src/patients.ts:133-140, apps/api/src/modules/patients/service.ts:26
Duplicate Prevention
To maintain a clean registry, the system performs duplicate checks based on patient demographics.
- Duplicate Identification: The system identifies potential duplicates by matching:
- Name (case-insensitive) AND Phone number.
- Name (case-insensitive) AND Date of Birth.
- Conflict Handling: If potential duplicates are found during registration, the API returns a
409 CONFLICT. The staff must explicitly provide anallowDuplicate: trueflag to override this warning and create the new record. - Auditing: Every duplicate override is recorded in the audit log.
Sources: apps/api/src/modules/patients/service.ts:153-172, apps/api/src/modules/patients/service.ts:360-368, apps/api/test/patients.int.test.ts:98-108
This sequence demonstrates the interaction flow when the system detects a potential duplicate patient.
Sources: apps/api/src/modules/patients/service.ts:166-174, apps/api/test/patients.int.test.ts:74-98
Family and Guardianship
The system maps relationships between patients to facilitate pediatric care and shared contact management.
Relationship Types
- Guardian: An adult linked to a patient who lacks their own mobile number. The system restricts guardianship to one level; a guardian cannot have their own guardian.
- Dependant: A patient managed by a specific guardian.
- Same Phone: Patients sharing the same mobile number but not explicitly linked via guardianship (e.g., spouses).
Sources: packages/contracts/src/patients.ts:51-53, apps/api/src/modules/patients/service.ts:376-392, apps/api/src/modules/patients/service.ts:408-433
Validation Rules
- A patient cannot be their own guardian.
- A child without a mobile number MUST be linked to a guardian.
- A patient who is already a guardian for others cannot be assigned a guardian.
Sources: apps/api/src/modules/patients/service.ts:145-151, apps/api/src/modules/patients/service.ts:376-392
Tagging System
Tags allow staff to categorize patients for clinical or administrative prioritization.
Tag Management Logic
- Assignment: Front desk and doctors can assign or remove tags.
- Archiving: Admins can archive tags. Archived tags remain on existing patient records but cannot be assigned to new patients.
- Prioritization: Tags with the
sortToTopproperty (e.g., "Emergency" or "Priority") cause patients to appear at the top of the clinic queue.
Sources: apps/api/src/modules/patients/tags.ts, apps/api/test/patients.int.test.ts:150-164, apps/api/src/modules/patients/service.ts:252-285
Default Tags
| Tag Name | Priority | Typical Color |
|---|---|---|
| Emergency | High (Sort to top) | #b91c1c |
| Priority | High (Sort to top) | #c2410c |
| VIP | Standard | #7e22ce |
| Insurance | Standard | #1d4ed8 |
Sources: packages/i18n/src/en.ts:108-112, apps/api/test/patients.int.test.ts:133-146
API Reference
The following table summarizes the primary endpoints for patient management.
| Method | Endpoint | Role Required | Description |
|---|---|---|---|
GET | /patients | Staff | List patients with optional search/tag filters. |
POST | /patients | Registrar | Register a new patient. |
GET | /patients/:id | Staff | Retrieve full patient details and family links. |
PATCH | /patients/:id | Registrar | Update demographics. |
POST | /patients/duplicate-check | Registrar | Check for existing records. |
PUT | /patients/:id/tags | Tagger | Update patient-specific tags. |
GET | /uhid-settings | Staff | Get current UHID configuration. |
PUT | /uhid-settings | Admin | Update UHID prefix and counter. |
Sources: apps/api/src/modules/patients/routes.ts:35-101
Data Structure
Patient Detail Model
export const PatientDetail = PatientSummary.extend({
email: z.string().nullable(),
address: z.string().nullable(),
bloodGroup: BloodGroup.nullable(),
language: Language,
emergencyContactName: z.string().nullable(),
emergencyContactPhone: z.string().nullable(),
guardian: PatientRef.nullable(),
family: z.array(PatientRef.extend({
relation: z.enum(['guardian', 'dependant', 'same_phone'])
})),
createdAt: z.iso.datetime(),
});
This contract defines the comprehensive demographic data captured for each patient.
Sources: packages/contracts/src/patients.ts:43-55
Conclusion
The Patient Management System acts as the foundation for the clinic's administrative workflow. By automating UHID allocation and enforcing strict rules for duplicate prevention and guardianship, it ensures that every patient has a single, verifiable identity linked to their family context and clinical priorities.