Skip to main content

Care Plan Service — Migration Plan

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD

Context​

The care-plan-service is a new service — there is no prior separate microservice to migrate from. However, some tenants may have clinical workflow data stored in external EHR or case management systems, or in legacy flat-file formats, that needs to be ingested.

Migration Scenarios​

Scenario 1: Greenfield deployment (most common)​

No migration needed. Tenants start creating care plans natively in the platform after the module is licensed and activated.

Steps:

  1. Enable ehr.care_plans entitlement for tenant in identity-service.
  2. Provision NATS stream CARE_PLAN_EVENTS for tenant.
  3. Notify clinical teams; provide training materials.

Scenario 2: Migration from external EHR care plan export (CSV/HL7 CDA)​

For tenants with existing care plans in external systems:

PhaseAction
ExtractExport care plans from source system as CSV, FHIR Bundle, or HL7 CDA
TransformMap to care-plan-service domain model (care plan + goals + activities + team)
LoadUse migration batch API (POST /api/v1/admin/care-plans/import) with migrationSource metadata
ValidateCompare record counts; verify FHIR read surface returns migrated data
CutoverDisable source system write access; redirect clinical workflow to platform

Scenario 3: Migration from monolithic EHR module within Ghasi platform​

If a previous monolithic EHR module stored care plan data in a shared Postgres schema:

  1. Run a one-time migration script that reads from the legacy schema and inserts into care_plans, care_plan_goals, care_plan_activities with correct tenant_id and new ULID IDs.
  2. Backfill version = 1 for all migrated records.
  3. Emit care_plan.care_plan.created.v1 events via outbox for each migrated plan so downstream services (chart, portal) are notified.
  4. Verify via integration test that all migrated plans are accessible via FHIR surface.

Rollback Plan​

  • Migration is additive; original data is not deleted until sign-off.
  • If migration fails, disable ehr.care_plans entitlement to hide the service from clinical UI.
  • Re-enable source system write access as fallback.

Data Retention Post-Migration​

  • Legacy source system data retained per tenant policy (typically 12 months post-migration).
  • Migration metadata (migrationSource, migrationDate) stored in care_plans.category as a custom extension coding.