Provider Directory Service — Migration Plan

Status: populated Owner: TBD Last updated: 2026-04-17

1. Context

Legacy sources: a single module provider-directory (version 1.0). Migration moves code and data into the unified provider-directory-service.

2. Tracks

Track	Description	Phase
T1	Code move into services/provider-directory-service; hexagonal refactor	M0
T2	Schema ETL into provider_directory.*; preserve IDs	M0
T3	Event renaming: legacy provider.* → canonical provider_directory.* with 30d dual-publish	M0 → M1
T4	Credential lifecycle introduction (new scanner + events)	M1
T5	Search index build (OpenSearch) + cut-over from DB-only search	M1
T6	FHIR R4 full projection rollout	M2

3. Data mapping

Legacy entity	New table	Notes
provider_profile	practitioners	JSON names + identifiers expanded
provider_role	practitioner_roles	Split privileges into JSON array
service_endpoint	endpoints	auth_method introduced with default none
(new) credentials	credentials	Populate from provider_profile.credentials[]

4. Event rename

Legacy	New
provider.created	provider_directory.practitioner.created.v1
provider.updated	provider_directory.practitioner.updated.v1
provider.credential.expiring	provider_directory.credential.expiring.v1
endpoint.updated	provider_directory.endpoint.updated.v1

Dual-publish for 30 days; consumers cut over; legacy retired.

5. Procedure (per tenant)

1. Freeze provider writes 15 min.
2. Snapshot legacy DB.
3. ETL to new schema; build OpenSearch index.
4. Smoke tests.
5. Unfreeze; dual-publish enabled.
6. 30d consumer cut-over.
7. Retire legacy subjects.

6. Rollback

Legacy DB read-only for 90 days. Feature flag toggles routing back to legacy service if incident.

7. Consumer impact

Consumer	Impact	Mitigation
scheduling-service	Event rename	Dual-subscribe during window
orders/medication/lab/rad	Privilege check endpoint moves	Both endpoints live 30d
interop-service	FHIR path unchanged	None
facility-service	New subscription to practitioner.created	Release-train coordinated