iOS Data Persistence

Generate production-ready data persistence infrastructure for iOS applications. Provides type-safe storage managers for UserDefaults, Core Data, Keychain, and file system operations with proper architecture, error handling, and SwiftUI integration.

Quick Start

Generate Storage Components

# Generate UserDefaults wrapper
python scripts/generate_userdefaults_wrapper.py ./Sources [Domain]

# Generate Core Data stack
python scripts/generate_coredata_stack.py ./Sources [ModelName] [BundleID] [EntityName]

# Generate Keychain service
python scripts/generate_keychain_service.py ./Sources [BundleID] [Domain]

# Generate File System manager
python scripts/generate_file_system_manager.py ./Sources [Domain]

Examples:

# For a mortgage calculator app
python scripts/generate_userdefaults_wrapper.py ./Sources Mortgage
python scripts/generate_coredata_stack.py ./Sources MortgageApp com.example.mortgage Calculation
python scripts/generate_keychain_service.py ./Sources com.example.mortgage Mortgage
python scripts/generate_file_system_manager.py ./Sources Mortgage

---

When to Use This Skill

Use this skill when you need to:

• ✅ Save user preferences and settings (theme, defaults, flags)
• ✅ Store structured data with relationships (calculations, history, notes)
• ✅ Secure sensitive information (tokens, passwords, API keys)
• ✅ Manage files and documents (PDFs, exports, cache)
• ✅ Enable multi-device sync (CloudKit integration)
• ✅ Implement calculation history (mortgage calculator, fitness tracker)
• ✅ Export and share data (reports, documents, backups)
• ✅ Persist app state (resume where user left off)

---

Storage Decision Guide

Use the decision tree to choose the right storage:

Is data sensitive (passwords, tokens, keys)?
├─ YES → Use Keychain (generate_keychain_service.py)
└─ NO → Continue

Is data simple (settings, flags, small values)?
├─ YES → Use UserDefaults (generate_userdefaults_wrapper.py)
└─ NO → Continue

Is data structured with relationships?
├─ YES → Use Core Data (generate_coredata_stack.py)
└─ NO → Continue

Is data file-based (PDFs, images, exports)?
├─ YES → Use File System (generate_file_system_manager.py)
└─ NO → Consider Core Data

Need multi-device sync?
└─ YES → Core Data + CloudKit

---

Available Scripts

1. UserDefaults Wrapper (generate_userdefaults_wrapper.py)

Purpose: Type-safe UserDefaults wrapper with Combine support

Generates:

• Property wrapper for type safety
• Observable preferences class
• Automatic persistence on change
• Reset methods
• Debugging utilities

Parameters:

• output_path: Directory to create the file (required)
• domain: Application domain (optional, default: "App")

Output: UserPreferences.swift

Features:

• ✅ Type-safe access with @UserDefault property wrapper
• ✅ SwiftUI @ObservableObject integration
• ✅ Automatic synchronization
• ✅ Reset to defaults functionality
• ✅ Debug printing support

2. Core Data Stack (generate_coredata_stack.py)

Purpose: Complete Core Data stack with proper lifecycle management

Generates:

• Persistent container setup
• Background context support
• CloudKit integration (optional)
• Error handling
• Batch operations
• Preview support

Parameters:

• output_path: Directory to create files (required)
• model_name: Name of Core Data model (optional, default: "Model")
• bundle_id: Bundle identifier for CloudKit (optional, default: "com.example.app")
• entity_name: Initial entity name (optional, default: "Item")

Output:

• CoreDataStack.swift
• {ModelName}.xcdatamodeld/ directory structure

Features:

• ✅ Singleton pattern with proper lifecycle
• ✅ Background context for long operations
• ✅ CloudKit sync ready
• ✅ Automatic merge from parent
• ✅ Batch delete/update operations
• ✅ In-memory stack for previews/tests

3. Keychain Service (generate_keychain_service.py)

Purpose: Secure credential storage with type-safe API

Generates:

• Keychain wrapper with error handling
• String and Data storage
• Codable object support
• Convenience methods for common operations

Parameters:

• output_path: Directory to create the file (required)
• bundle_id: Bundle identifier for keychain service (optional, default: "com.example.app")
• domain: Application domain (optional, default: "App")

Output: KeychainService.swift

Features:

• ✅ Type-safe save/retrieve operations
• ✅ Proper error handling
• ✅ Codable object support
• ✅ Authentication token helpers
• ✅ Existence checking
• ✅ Batch delete support

4. File System Manager (generate_file_system_manager.py)

Purpose: Document and file operations manager

Generates:

• Directory path helpers
• File CRUD operations
• Codable JSON support
• Cache management
• File attribute access

Parameters:

• output_path: Directory to create the file (required)
• domain: Application domain (optional, default: "App")

Output: FileSystemManager.swift

Features:

• ✅ Documents, cache, and temp directory access
• ✅ Domain-specific directory creation
• ✅ Save/load Data, String, Codable
• ✅ File copy/move/delete operations
• ✅ File size and date attributes
• ✅ Cache cleanup utilities
• ✅ Old file deletion

---

Workflow

Complete Persistence Setup

Step 1: Analyze Your Data Storage Needs

Identify what data needs to be persisted:

• User preferences → UserDefaults
• Structured app data → Core Data
• Sensitive credentials → Keychain
• Files and exports → File System

Step 2: Generate Required Storage Managers

# Generate all storage components
cd /path/to/your/project

# User preferences
python scripts/generate_userdefaults_wrapper.py ./Sources YourDomain

# Structured data
python scripts/generate_coredata_stack.py ./Sources YourModel com.yourcompany.app MainEntity

# Secure storage
python scripts/generate_keychain_service.py ./Sources com.yourcompany.app YourDomain

# File management
python scripts/generate_file_system_manager.py ./Sources YourDomain

Step 3: Design Your Core Data Model (if using Core Data)

1. Open YourModel.xcdatamodeld in Xcode
2. Design entities and relationships
3. Set Codegen to "Class Definition" for each entity
4. Add indexes for frequently queried attributes
5. Configure CloudKit sync if needed

Step 4: Initialize Storage in App

@main
struct YourApp: App {
    let coreDataStack = CoreDataStack.shared
    let preferences = UserPreferences.shared
    
    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(\.managedObjectContext, coreDataStack.viewContext)
                .environmentObject(preferences)
        }
    }
}

Step 5: Implement Domain Logic

Create repositories and view models that use the generated managers:

// Repository pattern for Core Data
final class DataRepository {
    private let context: NSManagedObjectContext
    
    init(context: NSManagedObjectContext = CoreDataStack.shared.viewContext) {
        self.context = context
    }
    
    func save(_ item: ItemData) -> Item {
        let entity = Item(context: context)
        // Map data to entity
        try? context.save()
        return entity
    }
    
    func fetchAll() -> [Item] {
        let request = Item.fetchRequest()
        return (try? context.fetch(request)) ?? []
    }
}

Step 6: Integrate with SwiftUI

Use the storage managers in your views:

struct SettingsView: View {
    @ObservedObject var prefs = UserPreferences.shared
    
    var body: some View {
        Form {
            Toggle("Feature Enabled", isOn: $prefs.featureEnabled)
        }
    }
}

struct DataListView: View {
    @Environment(\.managedObjectContext) private var viewContext
    
    @FetchRequest(
        sortDescriptors: [NSSortDescriptor(keyPath: \Item.date, ascending: false)]
    )
    private var items: FetchedResults<Item>
    
    var body: some View {
        List(items) { item in
            Text(item.name ?? "")
        }
    }
}

---

Reference Documentation

Comprehensive Guides

Read references/persistence-patterns.md for:

• Storage comparison and decision guide
• UserDefaults patterns and examples
• Core Data CRUD operations
• Keychain security patterns
• File system best practices
• CloudKit sync setup
• Data migration strategies
• Performance optimization
• Testing approaches

Read references/mortgage-calculator-guide.md for:

• Complete mortgage calculator persistence implementation
• User preferences setup
• Calculation history with Core Data
• Saved scenarios management
• Export functionality
• App integration examples
• SwiftUI patterns
• Real-world code examples

These references provide detailed patterns, examples, and best practices. Load them when implementing specific features or troubleshooting persistence issues.

---

Integration with Other Skills

Works Great With:

SwiftUI Component Library (Skill #7)

• Use generated components for preference UIs
• Form sections for settings screens
• Currency/percentage fields with persisted defaults

PDF Generation & Export (Skill #5)

• Export Core Data entities to PDF
• Save PDFs using FileSystemManager
• Share exports with UIActivityViewController

iOS Testing Suite Generator (Skill #4)

• Test with in-memory Core Data stack
• Mock keychain for secure testing
• Test file system operations

iOS Build CI/CD (Skill #6)

• Automated data migration testing
• Schema validation in CI
• Test data fixtures

---

Common Patterns

Pattern 1: User Preferences

// Generated with generate_userdefaults_wrapper.py
@ObservedObject var prefs = UserPreferences.shared

// In SwiftUI
Toggle("Feature", isOn: $prefs.featureEnabled)

// In code
if UserPreferences.shared.featureEnabled {
    // Do something
}

Pattern 2: Core Data Repository

// Create repository
let repo = DataRepository()

// Save
let item = repo.save(itemData)

// Fetch
let items = repo.fetchAll()

// Delete
repo.delete(item)

Pattern 3: Secure Storage

// Generated with generate_keychain_service.py
let keychain = KeychainService.shared

// Save token
try? keychain.save("token", forKey: "authToken")

// Retrieve
if let token = try? keychain.retrieveString(forKey: "authToken") {
    // Use token
}

// Check auth status
if keychain.isAuthenticated {
    // User is logged in
}

Pattern 4: File Management

// Generated with generate_file_system_manager.py
let fileManager = FileSystemManager.shared

// Save file
fileManager.save(data, to: "export.pdf", in: fileManager.documentsDirectory)

// Load file
if let data = fileManager.loadData(from: "export.pdf") {
    // Use data
}

// List files
let files = fileManager.contentsOfDirectory(at: fileManager.documentsDirectory)

---

Best Practices

UserDefaults

• ✅ Keep values small (< 1 MB total)
• ✅ Use for simple preferences only
• ✅ Don't store sensitive data
• ✅ Use property wrappers for type safety

Core Data

• ✅ Use background contexts for heavy operations
• ✅ Set proper fetch batch sizes
• ✅ Add indexes to frequently queried attributes
• ✅ Enable lightweight migration
• ✅ Use @FetchRequest in SwiftUI

Keychain

• ✅ Only store sensitive data
• ✅ Use for credentials, tokens, keys
• ✅ Handle errors appropriately
• ✅ Set proper accessibility levels

File System

• ✅ Use documents for user-visible files
• ✅ Use cache for temporary data
• ✅ Clean up old files regularly
• ✅ Exclude cache from backup if needed

---

Testing Support

All generated code includes testing support:

// In-memory Core Data for tests
let testStack = CoreDataStack.preview

// Mock keychain
class MockKeychain: KeychainService {
    var storage: [String: Data] = [:]
    // Override methods
}

// Test file system
class TestFileSystem: FileSystemManager {
    override var documentsDirectory: URL {
        FileManager.default.temporaryDirectory
    }
}

---

CloudKit Sync (Optional)

To enable CloudKit sync in Core Data:

1. Enable CloudKit capability in Xcode
2. Set enableCloudSync = true before accessing persistent container
3. Core Data stack is already configured for sync
4. Monitor sync status with notifications

CoreDataStack.shared.enableCloudSync = true
let container = CoreDataStack.shared.persistentContainer // Will use CloudKit

---

Troubleshooting

UserDefaults not persisting

• Call UserDefaults.standard.synchronize() if needed
• Check property wrapper implementation
• Verify key names are correct

Core Data errors

• Check data model versions
• Enable lightweight migration
• Verify entity names match classes
• Check predicate syntax

Keychain access denied

• Verify keychain entitlements
• Check accessibility settings
• Ensure proper error handling

File not found

• Check directory paths
• Verify file exists before loading
• Handle errors appropriately

---

Output Files

After running all scripts, you'll have:

YourProject/
├── Sources/
│   ├── UserPreferences.swift          # Type-safe preferences
│   ├── CoreDataStack.swift            # Complete Core Data setup
│   ├── YourModel.xcdatamodeld/        # Data model
│   ├── KeychainService.swift          # Secure credential storage
│   └── FileSystemManager.swift        # File operations

All files are:

• ✅ Production-ready
• ✅ Type-safe
• ✅ Well-documented
• ✅ SwiftUI-compatible
• ✅ Include examples
• ✅ Error handling included
• ✅ Testing support built-in

---

Next Steps After Generation

1. Customize preferences in UserPreferences.swift for your app
2. Design data model in .xcdatamodeld file
3. Create repositories for Core Data entities
4. Implement domain logic using storage managers
5. Integrate with UI using SwiftUI patterns
6. Add tests using preview/test support
7. Configure CloudKit if needed for sync

Your data persistence infrastructure is now complete and production-ready! 🎉