Migration & Backward Compatibility
Execution-layer artifact. Companion to ROADMAP.md. Defines backward compatibility rules across slices and migration requirements.
1. Overarching Rules
- No breaking changes without a migration window. Every breaking change ships with a migration script, a deprecation period (minimum 1 sprint), and a rollback plan.
- Additive changes are always safe. New optional fields, new endpoints, new events, new FHIR search parameters — these never break existing consumers.
- FHIR profiles evolve per FHIR versioning rules. New required elements require a new profile version. Existing profiles remain supported.
- Offline clients may be behind. Desktop Electron and mobile clients may not update immediately. Server APIs must support N-1 client versions for at least 2 sprints after a new version ships.
- Tenant data is never lost. Schema migrations are non-destructive. Columns are deprecated (nullable + hidden), never dropped, for at least 2 milestones.
2. Per-Slice Backward-Compatibility Requirements
| Artifact | Compat requirement |
|---|
| Tenant API | S1 adds clinical tenant configuration fields (additive; S0 clients unaffected) |
| FHIR Gateway | S1 adds clinical resource routes (additive; existing /fhir/R4 routes stable) |
| Event envelope | S1 publishes new clinical event types (additive; existing consumers unaffected) |
| Desktop SQLite | S1 adds clinical tables to SQLite (additive; S0 tables unchanged) |
| Sync protocol | S1 registers new aggregates for sync (additive; sync protocol unchanged) |
| AI orchestrator | S1 adds clinical prompts (additive; existing prompts unchanged) |
| Kong routes | S1 adds clinical service routes (additive; existing routes stable) |
| Keycloak | S1 adds clinical roles (additive; existing roles unchanged) |
Tenant migration: Existing S0 tenants receive S1 capabilities via module licensing activation. No data migration required.
S1 → S2 (Core Clinical → Orders & Diagnostics)
| Artifact | Compat requirement |
|---|
| FHIR resources | S2 adds ServiceRequest, DiagnosticReport (additive; existing Patient, Encounter, etc. unchanged) |
| Clinical notes | S2 may add order-linked note sections (additive optional fields; existing notes unchanged) |
| Desktop SQLite | S2 adds order/result tables (additive; clinical tables unchanged) |
| Terminology | S2 deepens code systems (additive data; existing codes unchanged; new codes added) |
| Billing | New service; no backward compatibility concern |
| Events | S2 publishes order/result events (additive; existing clinical events unchanged) |
| Patient chart | S2 adds orders/results tabs to chart aggregation (additive; existing tabs unchanged) |
Tenant migration: Existing clinics receive orders + billing via module activation. Terminology data seeded incrementally (background job, no downtime).
S2 → S3 (Orders & Diagnostics → Integrated Care)
| Artifact | Compat requirement |
|---|
| Orders-CPOE | S3 adds LIS-specific order routing (additive routing rules; existing order flow unchanged) |
| Results | S3 adds LIS-sourced results (same DiagnosticReport format; source field added) |
| Medication management | S3 adds pharmacy dispensing events (additive; existing prescribing unchanged) |
| FHIR resources | S3 adds MedicationDispense (additive; MedicationRequest unchanged) |
| E-prescribing | New gateway; existing medication workflows unaffected if gateway unavailable |
| Patient portal | New surface; no backward compatibility concern |
| Digital communication | New service; no backward compatibility concern |
| Desktop SQLite | S3 adds LIS + pharmacy tables (additive) |
Tenant migration: Hospitals activate LIS + pharmacy modules. LIS instrument integration requires per-facility configuration (no automated migration). Patient portal requires patient registration and consent opt-in.
| Artifact | Compat requirement |
|---|
| Billing | S4 deepens billing with claims + full accounting (additive features; basic billing unchanged) |
| Insurance | S4 deepens insurance with full claims integration (additive; eligibility checks unchanged) |
| FHIR resources | S4 adds ImagingStudy, Claim, ImmunizationRecommendation, CarePlan (additive) |
| HL7v2 | New adapter service; no backward compatibility concern for existing FHIR-only workflows |
| DICOM | New integration; no backward compatibility concern |
| AI orchestrator | S4 adds ONNX local inference (additive capability; cloud AI unchanged) |
| Population health | New service; consumes existing clinical data via events (no upstream changes) |
| Access-policy | S4 deepens ABAC (additive policies; existing RBAC unchanged) |
| Desktop SQLite | S4 adds imaging + billing + pop health tables (additive) |
Tenant migration: Hospitals activate PACS, claims, pop health via module licensing. PACS requires DICOM infrastructure (separate deployment step). HL7v2 requires per-partner adapter configuration. Population health computes from existing clinical data (no historical migration needed — computes forward).
| Artifact | Compat requirement |
|---|
| All APIs | S5 hardening: no breaking changes; performance improvements only |
| Multi-region | New infrastructure; existing single-region tenants unaffected |
| Mobile app | New surface; no backward compatibility concern for existing desktop/web users |
| SMART on FHIR | New capability; existing FHIR gateway endpoints unchanged |
| FHIR Bulk Data | New export endpoint; existing APIs unchanged |
| HMIS | New reporting layer; consumes existing data (no upstream changes) |
| White-label | Additive theming; existing tenants keep current theme unless explicitly changed |
| Desktop | S5 hardening: lazy bundles, a11y improvements (no breaking UX changes) |
Tenant migration: Existing tenants may opt into multi-region (requires data migration with scheduled downtime window). Mobile app available as optional client. White-label theming opt-in per tenant admin.
3. FHIR Profile Versioning
| Rule | Detail |
|---|
| Profile version format | ghasi-ehealth-{resource}-v{N} (e.g., ghasi-ehealth-patient-v1) |
| New optional elements | Same profile version (additive) |
| New required elements | New profile version (e.g., v1 → v2) |
| Deprecated elements | Marked deprecated in profile; remain in schema for 2 milestones |
| Removed elements | Only after 2 milestones of deprecation; requires ADR |
| Multi-version support | FHIR gateway routes to appropriate handler based on meta.profile |
4. Offline Client Versioning
| Rule | Detail |
|---|
| Desktop Electron updates | Auto-update via Electron updater; user prompted to restart |
| Forced update | Only for security-critical patches; user cannot skip |
| N-1 support | Server APIs support previous client version for 2 sprints |
| SQLite migration | Forward-only; migration scripts run on app startup |
| Mobile updates | App store update; forced update for security patches |
| Sync protocol versioning | Client sends protocol version in sync handshake; server adapts response |
5. Event Schema Evolution
| Rule | Detail |
|---|
| Schema format | CloudEvents v1.0 + versioned type field (e.g., ehealth.registration.patient.created.v1) |
| New event types | Safe to add anytime; no consumer impact |
| New optional fields in existing event | Safe; consumers must tolerate unknown fields |
| New required fields in existing event | New version (e.g., v1 → v2); dual-publish v1 + v2 during migration window |
| Removing fields | New version; old version published for 2 sprints |
| Consumer upgrade | Consumers must migrate to new version within deprecation window |
6. AI Prompt Evolution
| Rule | Detail |
|---|
| Prompt version format | {prompt-id}@{semver} (e.g., clinical-note-assist@1.2.0) |
| New prompts | Safe to add anytime |
| Prompt content changes | New minor version; A/B testing before full rollout |
| Prompt schema changes | New major version; old version remains available |
| Prompt deprecation | Per-tenant; admin chooses when to migrate |
| Prompt regression testing | Automated eval suite runs on every prompt change |
7. Database Schema Migration Rules
| Rule | Detail |
|---|
| Migration tool | TypeORM migrations (server) + custom SQLite migrations (desktop) |
| Migration direction | Forward-only; no down migrations in production |
| Column additions | Nullable with default; no downtime |
| Column renames | Add new column → dual-write → migrate reads → drop old column (3-sprint process) |
| Table additions | Safe; no downtime |
| Index additions | CREATE INDEX CONCURRENTLY (no lock) |
| Data migrations | Background job; never in transaction with schema change |
| Rollback plan | Every migration has documented rollback procedure (even if "not applicable") |