Domain Models & Business Logic

Relevant source files

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

• README.md
• packages/db/prisma/migrations/20261007120000_scheduling/migration.sql
• packages/db/prisma/migrations/20261007210000_consultations/migration.sql
• packages/contracts/src/consultations.ts
• apps/api/src/modules/scheduling/routes.ts
• apps/api/test/patients.int.test.ts
• apps/api/src/scripts/seed.ts
• packages/contracts/src/openapi.ts

The Domain Models and Business Logic represent the core rules and data structures governing the Digital Healthcare Platform. This layer centralizes standards for financial transactions, time management, patient identification, and clinical documentation to ensure consistency across the web, mobile, and API services.

Shared business rules live in the packages/domain directory, while data validation and API structure are defined in packages/contracts using Zod schemas. These rules enforce clinical safety, maintain multi-tenant isolation, and standardize health record formats.

Sources: README.md:1-50, packages/contracts/src/openapi.ts:1-20

Core Domain Standards

The platform implements specific technical standards to handle dates, currency, and patient identification across the Indian healthcare context.

Financial and Time Standards

• Currency: The system records all monetary values, including consultation fees and follow-up charges, in paise (integers) to avoid floating-point errors.
• Timezone: All scheduling and appointments use Indian Standard Time (IST). The default database timezone is set to Asia/Kolkata.
• Dates: IST dates are used for effective scheduling and appointment logic.

Sources: README.md:32-34, packages/db/prisma/migrations/20261007120000_scheduling/migration.sql:10-15, apps/api/src/scripts/seed.ts:110-120

Unique Healthcare Identifier (UHID)

The UHID logic assigns a unique identifier to every patient within an organisation.

• Structure: A UHID consists of an organisation-specific prefix (e.g., "DC") and a sequential number (e.g., "10001").
• Generation: The system skips UHIDs already in use (such as imported records) and increments the nextNumber counter in the uhid_settings table.
• Concurrency: The registration process ensures no two patients receive the same UHID during concurrent requests.

Sources: apps/api/test/patients.int.test.ts:35-70, apps/api/src/scripts/seed.ts:98-105

Scheduling and Availability Logic

The scheduling system manages how doctors offer slots across different clinics and consultation types.

Availability Structure

Doctors define their availability through availability_versions. This allows for future-dated changes to a weekly schedule without overwriting the current one.

Guard Rails and Constraints

The system enforces hard constraints at the database level to ensure schedule validity.

Entity	Constraint	Range/Rule
Consultation Type	default_duration_min	5 to 240 minutes
Booking Rules	horizon_days	1 to 365 days
Booking Rules	same_day_cutoff_minutes	0 to 1440 minutes
Availability	slot_minutes	5 to 240 minutes
Exceptions	date_check	end_date >= start_date

Sources: packages/db/prisma/migrations/20261007120000_scheduling/migration.sql:108-115

Clinical Data Model

Clinical records follow a strict lifecycle to maintain audit trails and patient safety.

Patient Chart and Vitals

The patient chart aggregates allergies, medical conditions, and medications.

• Sources: Entries are marked as either doctor or patient sourced. Patient-reported data remains unverified until a doctor confirms it.
• Immutability: Clinical entries (allergies, medications) are never physically deleted. To "remove" an entry, the system sets a removed_at timestamp and requires a removed_reason.
• Vitals: Supports recording BP (systolic/diastolic), pulse, temperature, SpO2, weight, height, and pain score. BMI is calculated automatically when both weight and height are present.

Sources: packages/contracts/src/consultations.ts:5-100, packages/db/prisma/migrations/20261007210000_consultations/migration.sql:5-60

Consultations

Consultation records contain the doctor's notes for a specific visit.

• Encryption: The notes_cipher field in the database indicates that clinical notes are stored encrypted.
• Locking: Once a prescription is signed, the consultation is marked as locked_at, preventing further edits.
• Revision Control: A revision counter prevents stale tabs from overwriting newer notes during concurrent editing sessions.

Sources: packages/contracts/src/consultations.ts:145-175, packages/db/prisma/migrations/20261007210000_consultations/migration.sql:85-100

Tenancy and Security Logic

The platform uses Postgres Row-Level Security (RLS) to enforce tenant isolation at the database layer.

• Isolation: Every table containing tenant data (e.g., clinics, patients, consultations) has an organisation_id column.
• Policy: The tenant_isolation policy ensures that users can only SELECT, INSERT, UPDATE, or DELETE rows belonging to their own organisation.
• Audit Log: Significant actions, such as viewing a patient chart or overriding a duplicate patient warning, are recorded in the audit log for compliance.

Sources: README.md:12-25, packages/db/prisma/migrations/20261007120000_scheduling/migration.sql:120-150, apps/api/test/patients.int.test.ts:80-90

Summary of Business Entities

Entity	Primary Responsibility	Key Identifier
Organisation	Top-level tenant container.	slug
Patient	Recipient of care; holds demographic data.	uhid
Clinic	Physical or virtual consulting location.	id (UUID)
ConsultationType	Defines service mode (video/audio/in-person) and fee.	name
Appointment	Links a Patient, Doctor, and Clinic at a specific Time.	id (UUID)

Sources: packages/contracts/src/openapi.ts:150-350, packages/db/prisma/migrations/20261007120000_scheduling/migration.sql:15-40