KMP Data Layer

Use for KMP data-layer work: repositories, data sources, source-of-truth design, network/persistence boundaries, offline-first behavior, sync, DTO/domain mapping, database choice, error handling, main-safety, and data API exposure.

Contract

Before implementing, identify:

• behavior: online-only, cache-first, offline-first, or local-only
• source of truth
• freshness/invalidation rules
• conflict resolution
• error model
• platform storage requirements
• persistence/network library target support
• test layer per behavior

Boundaries

• Repositories expose project-owned domain models or result types, not raw platform SDK types.
• DTOs stay near network boundaries.
• Database entities stay near persistence boundaries.
• Keep policy-bearing mapping explicit and tested.
• Shared code should not depend on Android Context, UIKit, file handles, or platform callbacks.

Libraries

Verify target support first:

• Ktor for shared HTTP when all targets need the same API client
• kotlinx.serialization when shared models are stable enough
• DataStore for small key-value settings when target support fits
• SQLDelight for SQL-first multiplatform persistence with broad target coverage
• Room KMP when current target support and KSP setup fit the project
• Platform-native persistence when shared persistence would add more risk than value

Use Klibs.io and official docs as target-support evidence. Do not put a library in commonMain because it works on Android.

Reliability

• Keep repository methods main-safe
• Bound retries explicitly
• Separate recoverable failures from programmer/configuration errors
• Do not swallow cancellation.
• Use clocks, dispatchers, and platform services through injectable abstractions when tests need control
• Make sync idempotent and resilient to duplicate callbacks

Testing

• Test mappers and policies as pure functions
• Test repositories with fakes or controlled test doubles
• Test offline/cache invalidation explicitly
• Test failure paths, stale data, conflict resolution, and retry boundaries