Skip to main content

medOS Migration

Internal scope — legacy HIS data migration toolkit and source-system adapters. Not a public-facing API surface.

medOS Migration is the onboarding engine for hospitals moving off another HIS product. It owns the full inbound pipeline — discovering a source schema, extracting and transforming records, deduplicating and validating them, bulk-loading into medOS, then reconciling source against target to prove the migration was complete. It is built as a NestJS/Moleculer service (ever-api-migration) and runs as an internal job runner rather than a live request-serving API.

11
modules
internal
scope
4
SQL dialects
5
country profiles

Responsibilities​

  • Schema discovery — introspect a source database, list tables and columns, and propose field mappings.
  • Extraction & transformation — pull source rows through dialect-aware adapters and reshape them into medOS entity shapes.
  • Deduplication & validation — collapse duplicate patient/encounter records and validate transformed data before load.
  • Bulk load — write migrated records into medOS, with idempotent re-runs.
  • Reconciliation — compare source and target row counts and checksums; surface gaps.
  • Dead-letter handling — capture records that fail any stage into a dead-letter queue for human review and re-drive.
  • EHR-to-EHR sync — adapter-based synchronization from named source EHR systems.
  • Country & tenant awareness — apply per-country profiles (names, dates, encoding, validators) and keep migrations tenant-scoped.

Major modules​

ModulePurpose
migrationJobMigration job lifecycle — create, run, track, resume
schemaDiscoverySource-schema introspection and mapping proposals
extractionSource data extraction through dialect adapters
transformData transformation engine (source shape to medOS shape)
loadBulk loader into medOS entities
dedupRecord deduplication
reconcileSource vs. target reconciliation and gap reporting
validationPre-load data validators and report generation
ehrSyncEHR-to-EHR synchronization
dlqDead-letter queue for failed records
fieldReview / mappingStudioHuman-in-the-loop field mapping and review
countryPer-country profile resolution
tenantMulti-tenant scoping
capabilityAdapter / connector capability reporting
airbyteAirbyte-style connector integration
dbtdbt-style transformation hooks

Source adapters​

The service resolves a source system through an adapter framework. Built-in adapters cover both raw SQL sources and named EHR products.

SQL dialects

Database sources

Dialect presets cover Oracle, MySQL, PostgreSQL and MSSQL — including per-version pagination and connection-style quirks.

oraclemysqlpostgresqlmssql
EHR adapters

Source EHR products

A shared adapter framework wraps named source EHR systems behind one extraction contract.

epictrakcaretakecarefile
Localization

Country profiles

Per-country profiles handle name formats, date conventions, character encoding and field validators.

thailandjapanphilippinesusasweden

Pipeline flow​

   source DB / EHR / file
            │
            ▼
   ┌─────────────────┐
   │ schemaDiscovery │  introspect + propose mappings
   └────────┬────────┘
            ▼
   ┌─────────────────┐
   │   extraction    │  dialect / EHR adapter
   └────────┬────────┘
            ▼
   ┌─────────────────┐    ┌──────────┐
   │    transform    │───▶│  dedup   │
   └────────┬────────┘    └────┬─────┘
            ▼                  ▼
   ┌─────────────────┐    ┌──────────┐
   │   validation    │───▶│   dlq    │  failed records
   └────────┬────────┘    └──────────┘
            ▼
   ┌─────────────────┐
   │      load       │  bulk write into medOS
   └────────┬────────┘
            ▼
   ┌─────────────────┐
   │    reconcile    │  source ⇄ target counts/checksums
   └─────────────────┘

Each stage is driven by a migrationJob, so a run can be re-driven from the dead-letter queue without re-extracting clean records.

Integration notes​

  • The service consumes source databases (SQL dialects above), flat files (file adapter), and named EHR systems through the adapter framework.
  • It writes into medOS via the standard backend write paths; it does not write to Supabase read-model tables directly.
  • Country behavior is data-driven via the country registry and per-country profiles — adding a region is a profile, not new service code.
  • A synthetic-data generator is available for building test corpora per country.
  • SYS-10 — Legacy Data Migration Toolkit
  • SYS-9 — Tenant Provisioning