LocalData/Documentation/Design.md

LocalData Architecture and Design

Overview

LocalData is a typed, discoverable namespace for persisted application data. It provides a consistent API for reading, writing, and removing data across multiple storage domains while enforcing security and serialization policies.

Key Components

StorageRouter

The central actor that coordinates all storage operations. It acts as the primary API surface and handles routing, catalog validation, and migration.

StorageKey

A generic struct that defines the metadata for a single piece of persistent data.

• Value: The type of the data (Codable).
• Domain: Where the data is stored (UserDefaults, Keychain, FileSystem, etc.).
• Security: How the data is secured (None, Keychain-native, or custom Encryption).
• Serializer: How the data is encoded to/from Data (JSON, Plist, etc.).
• SyncPolicy: Rules for syncing data between iPhone and Watch.

Helper Actors

Specialized actors for each storage domain:

• KeychainHelper: Manages Keychain operations.
• UserDefaultsHelper: Manages UserDefaults and App Group defaults.
• FileStorageHelper: Manages local and App Group file storage.
• EncryptionHelper: Provides AES and ChaCha20 encryption.
• SyncHelper: Manages WatchConnectivity synchronization.

Routing Logic

1. Validation: Check if the key is registered in the catalog (if registered) and if it's available on the current platform.
2. Serialization: Convert the value to Data using the specified serializer.
3. Security (Apply): Apply encryption or security policies.
4. Storage: Delegate the write operation to the appropriate helper.
5. Sync: Trigger a sync update if the policy allows.

Security Model

• None: Data is stored as-is (e.g., standard UserDefaults).
• Keychain: Native hardware security using the iOS Keychain.
• Encrypted: Custom encryption (AES-256-GCM or ChaCha20-Poly1305) with key derivation (PBKDF2/HKDF).
• File Protection: Uses iOS "Complete File Protection" for encrypted file system writes.