Registration Service — Service Overview
Status: populated Owner: TBD Last updated: 2026-04-17 Companion: Service Template · 03 platform-services · 02 DDD
1. Purpose
The registration-service is the Master Patient Index (MPI) and patient identity authority for the Ghasi national eHealth platform. It owns every patient record and encounter registration event, publishing stable identity keys consumed by all downstream platform services (EHR, pharmacy, LIS, population health, immunizations, scheduling, and others).
It is an always-on, core baseline service. No clinical work can begin without a registered patient identity.
2. Bounded Context
| Attribute | Value |
|---|---|
| Bounded context | registration |
| Module ID (legacy) | ADMIN-REG |
| DDD context type | Core domain |
| Bundle | Core EHR — always-on baseline |
| License key | ehr.registration |
| FHIR canonical resources | Patient, Encounter, RelatedPerson, Consent |
3. Responsibilities
| In scope | Out of scope |
|---|---|
| Patient identity creation, update, search | De-identified cohort analytics (owned by population-health-service) |
| National ID capture and validation (NID / tazkira) | Clinical note authoring |
| Master Patient Index: MPI scoring, duplicate detection | Scheduling (owns Appointment, Slot) |
| Merge / unmerge workflow with survivorship rules | Pharmacy dispensing |
| Encounter registration and status lifecycle | Full pedigree / clinical family tree |
| Provisional, unidentified, and newborn registration | Lab orders or results |
| Vital status (deceased) recording and correction | Billing / claims |
| Next-of-kin / relationship graph | Insurance verification |
| Patient portrait (photo) with consent and retention | |
| Extensible patient attribute bundles (employment, appearance) | |
| Consent flags (SMS / email communication preference) | |
| HL7 v2 ADT emission/consumption (via interop-service adapter) | |
FHIR R4 Patient and Encounter read/write surface | |
Stable stablePatientId published to NATS for all consumers |
4. Upstream and Downstream Dependencies
5. Slice Involvement
| Slice | Involvement |
|---|---|
| S0 (core identity) | Owner — patient + encounter CRUD, MPI, events |
| S1 (clinical workflow) | Provider — stable patient key consumed by all clinical services |
| S2 (interop) | Participant — FHIR Patient/Encounter surface; HL7 ADT via interop adapter |
| S3 (national programs) | Owner — alternate ID, unidentified intake, portrait, family graph |
6. Key Architectural Decisions
| Decision | Rationale |
|---|---|
FHIR-first: Patient and Encounter are canonical | No competing shadow model; downstream consumers use FHIR Patient reference |
| MPI scoring is internal (probabilistic) | Phase 1 does not mandate external MPI; adapter hook exists for IHE PIX/PDQ |
| Merge is safety-critical human workflow | No AI-automated merge decisions; AI provides hints only (Tier A, HITL) |
stablePatientId = internal UUID (duplicated for integrators) | Cross-program binding without exposing DB row IDs |
| Optimistic locking on all mutations | Prevents concurrent-update race conditions without heavy locks |
| Provisional / unidentified records never block on MPI | Emergency care proceeds; duplicate review is async |
Tenant isolation via PostgreSQL RLS + JWT tenantId | Multi-tenant safety at DB layer |
7. Architecture Diagram
8. Source Reconciliation
Single source module _sources/registration/. The enterprise national eHealth extensions (FR-REG-023–028: alternate ID, unidentified intake, portrait, extensible metadata, family graph) are drawn from _sources/registration/enhancement/ENTERPRISE_NATIONAL_EHEALTH_REQUIREMENTS.md and merged into this service's canonical documentation set. No module split is required — all functionality lives in registration-service.
9. Open Questions
- IHE PIX/PDQ counterparty deployment details are jurisdiction-specific (Afghanistan MoPH integration timeline TBD).
- Biometric reference as alternate identity evidence: legal framework per jurisdiction required before implementation.