Skip to main content

Population Health Service — Migration Plan

Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template

1. Legacy Context​

The _sources/health-population/ module was designed as a standalone analytics service within the original Ghasi EHR monolith. It had no separate deployment; analytics queries ran directly against the EHR PostgreSQL schema. This migration plan documents how tenants and data move into the standalone population-health-service.

2. Migration Phases​

Phase 0 — Schema Bootstrap (S0)​

  • Create population_health PostgreSQL database (isolated from EHR DB)
  • Run initial Drizzle ORM migrations
  • Bootstrap NATS JetStream stream POPULATION_HEALTH
  • Deploy service in read-only shadow mode alongside legacy EHR analytics

Phase 1 — Cohort and Registry Backfill (S1)​

StepAction
1.1Export existing cohort definitions from EHR population_cohorts table using migration script
1.2Translate legacy predicate format to new CohortExpressionNode JSON DSL
1.3Import into population-health-service with version=1 and status Active
1.4Backfill disease registry entries from EHR problem-list and encounter projections
1.5Run initial cohort refresh for all migrated cohorts; validate membership counts against legacy

Phase 2 — Quality Metrics and Risk Scores (S2)​

StepAction
2.1Backfill last 4 quarters of quality metric snapshots from legacy reporting tables
2.2Compute initial risk scores using new scoring models; compare against legacy tier assignments
2.3Migrate manual risk overrides with reason and auditor ID preserved
2.4Validate HEDIS/QOF rates match ±2% tolerance vs legacy reports

Phase 3 — HMIS DHIS2 Cutover (S3)​

StepAction
3.1Run parallel DHIS2 push (both legacy and new service) for one month
3.2Compare DHIS2 import counts and data values between runs
3.3MoPH sign-off on data equivalence
3.4Disable legacy push; new service becomes sole DHIS2 feed

Phase 4 — Decommission Legacy Analytics (S4)​

  • Remove legacy analytics queries from EHR service
  • Archive legacy tables with 90-day retention before drop
  • Update all internal service consumers to use population-health API

3. Rollback Plan​

  • All migrated data is additive (new DB); legacy DB remains intact during phases 0–3
  • Phase 3 parallel run allows rollback to legacy DHIS2 push within same reporting window
  • Phase 4 is irreversible — requires MoPH sign-off before proceeding

4. Zero-Downtime Requirements​

  • Migration scripts run with row-level locking only; no full table locks
  • Dashboard and registry endpoints remain available during backfill (serve from new DB)
  • Cohort refresh jobs paused during schema migrations; resume automatically

5. Data Validation Checklist​

  • Cohort membership counts match legacy ±1% for all migrated cohorts
  • Quality metric rates match ±2% for last 4 quarters
  • Risk tier distributions match ±5% across tenant populations
  • DHIS2 parallel run shows 100% import acceptance
  • All manual risk overrides migrated with audit trail intact