A patient in Dudoxx HMS is a dual-store entity: a User row in Prisma (ddx_api_main) for operational identity (auth, MRN, insurance), and a FHIR Patient resource in HAPI for clinical identity (demographics, consent, family relationships) — linked by UUID with a fhirPatientId field on the Prisma User row.
Business Purpose
Patient registration is the entry point for every clinical workflow. A patient who is not yet registered cannot have appointments booked, visits opened, or clinical data recorded. The registration process must:
Create a stable identity that persists across visits and practitioners.
Assign a Medical Record Number (MRN) that serves as the legal identifier for all clinical documents.
Sync demographics to FHIR so the patient can be found by any FHIR-aware component (lab system, insurance gateway, AI agent).
Optionally capture family/emergency contacts and insurance coverage at registration time.
Dudoxx HMS satisfies all four requirements through a transactional PatientCreationService that orchestrates Prisma and HAPI writes atomically, with compensation logic if either store fails.
Audiences
Investor: Patient count is the primary adoption metric. The dual Prisma+FHIR registration enables both operational scalability (Prisma fast-path for appointments) and regulatory compliance (FHIR for insurance, referral, and ePA integration) without maintaining a synchronization job.
Clinical buyer (doctor/nurse/receptionist): Receptionists register patients through the patient portal form. The system auto-assigns an MRN on creation. Existing patients can be found by name fuzzy search, phone, or MRN. Doctors see full demographics + active conditions + medications in the medical card on the patient detail page.
Developer/partner: GET|POST|PUT|PATCH|DELETE /api/v1/patients. Patient UUID (Prisma user.id) is the stable API identifier. FHIR Patient numeric ID is an internal implementation detail resolved by PatientIdResolverService. Fuzzy patient search available via GET /api/v1/patients?search={term}. Batch info lookup at POST /api/v1/patients/batch-info.
Internal (ops/support): Patient creation is a 9-step transactional process with state tracking in Prisma. If creation fails mid-flight, the compensateFhirCreate() path deletes any partially-created FHIR resources. MRN format is controlled by MrnService and configured per organization.
Architecture
diagram
PatientsCrudController (/api/v1/patients)
└── PatientsService (orchestrator — delegates to 11 sub-services)
├── PatientCreationService — transactional Prisma+FHIR+MRN creation
├── PatientCrudService — FHIR read/update/delete; IFhirClient
├── PatientSearchService — fuzzy search across Prisma + FHIR
├── PatientAggregationService — parallel FHIR fetch → PatientSummaryResponseDto
├── PatientIdResolverService — UUID ↔ FHIR Patient numeric ID resolution
├── PatientIdResolver (sync) — fast local cache for ID resolution
├── PatientMedicationService — patient-level medication management
├── PatientAttachmentService — document/file attachments
├── PatientCareTeamService — FHIR CareTeam resources
├── PatientFavoritesActivity — favorite/recently-viewed flags
└── PatientEverythingService — FHIR $everything export
PatientCreationService creation steps (9 phases):
1. findExistingPatient() — dedup check by email hash
2. generateMrn() — MrnService.assignMrn()
3. createFhirPatient() — POST Patient to HAPI
4. createFhirPerson() — POST Person (identity link for MDM)
5. buildPersonLink() — link Person → Patient
6. persistDbState() — Prisma User + OrganizationMember + fhir_resource_link
7. createRelatedPersons() — FHIR RelatedPerson for emergency contacts (with retry backoff)
8. toEmergencyContactCreate() — Prisma EmergencyContact rows
9. toInsuranceCoverageCreate()— Prisma InsuranceCoverage rows
If any HAPI write fails, compensateFhirCreate() deletes the Patient and Person resources to prevent orphaned FHIR data.
See coding_context/ddx-hms-context.md §Clinical for the module map.
Normalized via normalizeGender() + formatFhirAddress() helper functions
Fuzzy search
PatientSearchService — Prisma fulltext + FHIR text search
Returns ranked results across both stores; used by receptionist appointment booking
Text aggregation
PatientTextAggregationService — builds LLM-ready patient text
Used by TUCAN AI to inject patient context without a separate API call
Key design decision: The Prisma User UUID is the stable public API identifier — NOT the FHIR Patient numeric ID. All endpoint routes use UUIDs (/patients/:id). The PatientIdResolverService maintains a cache of UUID → FHIR numeric ID mappings to avoid per-request HAPI lookups. Passing a FHIR numeric ID to any patient endpoint returns 404.
Data Flow
New patient registration
Business outcome: Receptionist registers a new patient; within 3 seconds, the patient appears in the system with an MRN and a FHIR Patient record.
Technical mechanism:
POST /api/v1/patients with { firstName, lastName, email, birthDate, gender, phone, address, emergencyContacts[], insuranceCoverages[] } and X-Clinic-ID.
PatientsCrudController.createPatient() (patients-crud.controller.ts:322) delegates to PatientsService.createPatient().
ddx-api/src/clinical/patients/services/patient-id-resolver.service.ts:1 — PatientIdResolverService — UUID ↔ FHIR Patient ID resolution with sync throttle (SYNC_THROTTLE_MS); resolveFhirPatientId() used by every FHIR-writing service
ddx-api/src/clinical/patients/services/patient-aggregation.service.ts:72 — PatientAggregationService — parallel FHIR fetch for medical card; see Medical Cards
ensureFhirPatient() is critical: Any patient created before the FHIR sync (or via seeder without FHIR write) will have fhirPatientId = null. PatientsService.ensureFhirPatient() (patients.service.ts:411) creates the FHIR Patient lazily on the next read. This is called by GET /visits/me before returning visit history. Services that assume fhirPatientId is non-null will throw NotFoundException for pre-migration patients.
UUID is the stable identifier: FHIR Patient numeric IDs change if HAPI is wiped and re-seeded. The Prisma UUID (user.id) never changes. External systems must use UUIDs in API calls.
Email hash dedup: PatientCreationService.findExistingPatient() checks emailHash (SHA-256 of lowercase email) — not raw email — to avoid storing PII in the lookup index. Registering the same patient email twice throws ConflictException.
RelatedPerson retry: HAPI sometimes returns a transient error when creating RelatedPerson resources immediately after Person creation. createOneRelatedPersonWithRetry() uses exponential backoff (RELATED_PERSON_BACKOFF_MS, RELATED_PERSON_MAX_ATTEMPTS) before giving up (non-fatal — patient is still created).
Patch vs PUT semantics: PATCH /patients/:id is a partial update (only supplied fields are changed in Prisma + FHIR). PUT /patients/:id is a full replace. Use PATCH for UI edit forms; PUT for bulk import.
FHIR patient ID resolution cache: PatientIdResolverService caches UUID→FHIR ID mappings. If a FHIR Patient is deleted and re-created (e.g., after a HAPI reset in dev), the cache must be cleared or the service restarted to pick up the new FHIR IDs.