Realm Atlas Device SDK: Minimal Local‑First Design, Trust Boundaries, and Failure‑Mode Guidance

Problem Statement and Takeaway

You are building a mobile or edge application that must store data locally with ACID guarantees, work offline, and optionally synchronize changes across devices or with a backend service. The core decision is whether to keep Realm purely local or to enable Device Sync. The takeaway is: start with a single encrypted Realm file per user, add Sync only when cross‑device sharing is required, and enforce clear trust boundaries and operational checks to avoid common failure modes.

Requirements

• Embedded, local persistence with ACID compliance.
• Optional sync to Atlas for multi‑device visibility or server‑side processing.
• Encryption at rest with a key stored outside the Realm file.
• Robust handling of network partitions, schema migrations, and conflict resolution.
• Visibility into sync health, file growth, and resource usage.

Minimal Design: One Local Realm per User

The simplest, most robust architecture is a single Realm file per authenticated user. The file contains all domain objects and is versioned via schemaVersion. If sync is needed, the same file is used for both local and remote operations; otherwise it acts as a pure local store.

# Swift example (illustrative, not tested)
import RealmSwift

// Encryption key should be fetched from the platform secure store
let key = try! SymmetricKey.generate() // placeholder: retrieve from Keychain/Keystore
let config = Realm.Configuration(
    schemaVersion: 4,
    migrationBlock: { migration, oldSchemaVersion in
        if oldSchemaVersion < 3 {
            migration.enumerateObjects(ofType: Task.className()) { obj, _ in
                obj!["isCompleted"] = false
            }
        }
    },
    deleteRealmIfMigrationNeeded: false,
    encryptionKey: key
)
let realm = try! Realm(configuration: config)

When Device Sync is required, add a SyncConfiguration that references the authenticated user and a partition value. The partition value defines the trust boundary between local and remote data.

# Swift example for sync (illustrative, not tested)
let syncConfig = SyncConfiguration(
    user: user,
    partitionValue: "user_id=\(user.id)"
)
let realm = try! Realm(configuration: syncConfig)

Trust Boundaries

Realm operates across three distinct trust zones:

1. Device Edge – The local Realm file and its encryption key. The key must reside in a platform secure store (iOS Keychain, Android Keystore) and never be written to plain‑text files or user defaults.
2. Network Layer – TLS‑encrypted traffic between the device and Atlas. Network policies should restrict outbound sync to the Atlas domain on port 443.
3. Atlas Cluster – The server side holds the master copy. Access controls, IP whitelisting, and role‑based permissions must isolate each user’s partition.

A compromise of the device‑edge encryption key or sync credentials immediately exposes data. Therefore, enforce key‑rotation policies on the device and enable audit logging on Atlas.

Operational Checks

To maintain a healthy sync environment, implement the following runtime checks:

Check	Description	Implementation Hint
Sync Session Status	Is the session active, paused, or errored?	Monitor SyncSession.state; alert if .error persists >5 min.
Schema Migration Success	Did the migration block execute without throwing?	Wrap migration in do‑catch; log failures and retry on next launch.
Local File Size & Compaction	Is the file growing unchecked?	Call realm.compact() during low‑usage windows; enforce a size ceiling (e.g., 100 MB).
Battery & Network Constraints	Is sync throttled appropriately?	Set SyncConfiguration.isAutomatic = false; schedule sync on Wi‑Fi or when charging.
Encryption Verification	Is the file encrypted on disk?	Confirm realm.configuration.encryptionKey != nil; verify key storage location.

Automate these checks with a background service that forwards metrics to your observability platform. Trigger alerts when sync errors exceed a threshold or when file size approaches the policy limit.

Failure Modes and Mitigation

• Network Partition – Local writes continue while sync stalls. Mitigation: treat local changes as provisional; show an offline indicator and retry sync when connectivity returns.
• Backward‑Incompatible Migration – A newer schema version cannot migrate an older file, blocking app start. Mitigation: keep deleteRealmIfMigrationNeeded false; run exhaustive migration tests against a production‑sized Realm file in staging.
• Conflict Divergence – The same record is modified on two devices before sync. Mitigation: decide on a conflict‑resolution policy (server‑wins, client‑wins, or custom merge) and configure it via SyncConfiguration.conflictResolution or Realm’s Object.update hooks.
• Over‑Fetching via Flexible Sync – Broad subscription queries pull excessive data. Mitigation: limit subscriptions to the minimal set of fields and ensure filter columns are indexed.
• Data Residency Violation – Syncing to Atlas moves data outside a permitted jurisdiction. Mitigation: disable sync and enforce local‑only storage; if sync becomes necessary, deploy a private Atlas cluster in the required region.

When the Design Should Evolve

The minimal design remains valid until one or more of the following conditions arise:

• Real‑time collaboration is required across many devices, demanding server‑side conflict merges.
• Analytics or reporting need efficient joins across many tables, which Realm does not optimize.
• Multi‑tenant isolation must go beyond the partition value (e.g., separate schemas per tenant).
• Regulatory constraints forbid any data leaving the device, making sync infeasible.

When these conditions appear, introduce an explicit backend API layer (e.g., GraphQL or REST) that sits between Realm and the Atlas cluster. This layer can perform server‑side joins, enforce additional access controls, and expose only the data transformations needed by the client, keeping the embedded database focused on local persistence.

Practical Verification Checklist

1. Perform a staged deployment with airplane‑mode toggling; confirm that local writes persist and sync resumes correctly after reconnection.
2. Execute a schema migration on a copy of a production‑sized Realm file; measure startup time and verify data integrity.
3. Inspect the on‑disk Realm file (e.g., using openssl enc -d -in file.realm -out plain with the known key) to confirm encryption; ensure the key is not recoverable from the app bundle.
4. Review Atlas sync logs for ConflictResolutionFailed entries; verify that the chosen resolution strategy is applied.
5. Capture network traffic with a tool like Wireshark or platform‑specific profiler; ensure TLS termination and that only the Atlas domain is contacted for sync.