Migrate FHIR Engine to Kotlin Multiplatform (KMP)

[FikriMilano]

Migrate the existing FHIR Engine to Kotlin Multiplatform (KMP) to enable native support for Android, iOS, and JVM/Desktop while leveraging KMP compatible libraries (Room, Datastore, kotlin-fhir) and preserving existing entities, DAOs, and migrations with minimal changes.

1. Engine Setup (Init engine-kmp) Setup Empty Engine KMP module #2959
2. Core Data Model Migration
   • Migrate Fhirengine interface, LocalChange, SearchResult, Configuration, Index entities to kotlin-fhir in commonMain.
   • For Search DSL, implement typed search parameters in kotlin-fhir Generate typed search parameter constants for FHIR resources kotlin-fhir#74
3. Database Layer Migration
   • Move database definition, room entities, DAOs to commonMain.
   • Database builders and encryption implementations with the Kotlin expect/actual for each platform
   • Use BundledSQLiteDriver so other platforms can understand SQLite
   • Use Ktor to replace Retrofit and Okhttp
4. Sync Layer Migration
   • Already pure kotlin and coroutines
   • Move FhirSynchronizer, ConflictResolver, DataSource, SyncJobStatus, etc to commonMain
   • Use Kermit to replace Timber for logging
   • Use kotlinx-serialization to replace Gson

[FikriMilano]

• Try simple kmp app for database in each platform
• Possible DB replacement: sql delight, realm
• Might want to try no sql because we use complicated index
• Room DB might support js/wasm in the future
• Separate work of migration to kmp, with no sql
• Database encryption between platforms, support? android and ios only

[ellykits]

Overview

This discussion outlines the architectural, technical, and strategic
considerations involved in migrating the existing FHIR Engine
implementation to Kotlin Multiplatform (KMP).

The migration is non-trivial and introduces platform constraints,
dependency shifts, database redesign questions, and long-term
maintainability trade-offs.

This document is intended to guide architectural decision-making before
any irreversible implementation begins.

---

1. SQLCipher Support in KMP

Problem

SQLCipher is not supported in Kotlin Multiplatform.

Impact

• Loss of built-in encrypted database support across platforms
• Security model divergence between Android and iOS
• Increased implementation complexity

Potential Resolution

• Use platform-specific encryption layers
  • Android: SQLCipher or encrypted Room
  • iOS: Native encrypted database mechanisms
• Introduce abstraction layer in shared module

Trade-off

• More code
• Increased maintenance burden
• Platform divergence risk

---

2. Background Task Management

Problem

There is no direct equivalent of Android WorkManager in KMP.

Impact

• Background sync and job scheduling must be implemented per platform
• Shared logic becomes limited to orchestration only

Potential Resolution

• Define common scheduling interface in shared module
• Implement platform-specific schedulers:
  • Android: WorkManager
  • iOS: BackgroundTasks framework
• Accept increased engineering time

Trade-off

• More platform code
• Testing complexity increases
• Longer development cycle

---

3. Migration from HAPI to Kotlin-FHIR

Problem

Switching from HAPI (Java-based) to Kotlin-FHIR introduces major
refactor work.

Impact

• Model layer rewrite
• Parsing and serialization adjustments
• Compatibility verification with existing resources
• Validation logic rewrite

Risk

• High engineering effort
• Potential behavioral differences
• Migration bugs in resource handling

---

4. StructureMap & Extraction Logic

Problem

StructureMap-based extraction logic is complex and no longer directly
available in SDC.

Impact

• Loss of automatic mapping logic
• Increased custom implementation effort

Potential Resolution

• Implement template-based extraction engine
• Define mapping DSL in shared module

Trade-off

• Significant new development effort
• Longer delivery timeline
• Higher maintenance complexity

This is a structural redesign, not a minor migration.

---

5. Database Architecture Strategy

Critical Decision Area

Option A: Maintain Existing Table Structures

• Minimal disruption
• Faster migration
• Technical debt retained

Option B: Adopt Flattened Table Approach

• Query performance optimization
• Better filtering capability
• Cleaner sync strategy
• Requires:
  • DB entity refactor
  • DAO rewrite
  • Search API refactor
  • Sync API redesign

This option is complex and requires significant architectural
discussion.

---

6. Fresh Implementation vs Incremental Migration

Question

Should FHIR Engine be re-implemented from scratch for KMP?

Considerations

• Clean architecture opportunity
• Removal of legacy constraints
• Higher upfront cost
• Longer time to delivery

Hybrid Approach Proposal

• Maintain normalized canonical storage
• Provide flattened "views" or derived tables
• Keep extraction logic modular
• Gradually migrate components

This reduces risk while allowing architectural evolution.

---