# 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 protocol 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.