iOS Storage Guide

Purpose: Navigation hub for ALL storage decisions — database vs files, local vs cloud, specific locations iOS Version: iOS 17+ (iOS 26+ for latest features) Context: Complete storage decision framework integrating SwiftData (WWDC 2023), CKSyncEngine (WWDC 2023), and file management best practices

When to Use This Skill

✅ Use this skill when:

• Starting a new project and choosing storage approach
• Asking "where should I store this data?"
• Deciding between SwiftData, Core Data, SQLite, or files
• Choosing between CloudKit and iCloud Drive for sync
• Determining Documents vs Caches vs Application Support
• Planning data architecture for offline/online scenarios
• Migrating from one storage solution to another
• Debugging "files disappeared" or "data not syncing"

❌ Do NOT use this skill for:

• SwiftData implementation details (use axiom-swiftdata skill)
• SQLite/GRDB specifics (use axiom-sqlitedata or axiom-grdb skills)
• CloudKit sync implementation (use axiom-cloudkit-ref skill)
• File protection APIs (use axiom-file-protection-ref skill)

Related Skills:

• Existing database skills: axiom-swiftdata, axiom-sqlitedata, axiom-grdb
• New file skills: axiom-file-protection-ref, axiom-storage-management-ref, axiom-storage-diag
• New cloud skills: axiom-cloudkit-ref, axiom-icloud-drive-ref, axiom-cloud-sync-diag

Core Philosophy

"Choose the right tool for your data shape. Then choose the right location."

Storage decisions have two dimensions:

1. Format: How is data structured? (Queryable records vs files)
2. Location: Where is it stored? (Local vs cloud, which directory)

Getting the format wrong forces workarounds. Getting the location wrong causes data loss or backup bloat.

---

The Complete Decision Tree

Level 1: Format — What Are You Storing?

What is the shape of your data?

├─ STRUCTURED DATA (queryable records, relationships, search)
│   Examples: User profiles, task lists, notes, contacts, transactions
│   → Continue to "Structured Data Path" below
│
└─ FILES (documents, images, videos, downloads, caches)
    Examples: Photos, PDFs, downloaded content, thumbnails, temp files
    → Continue to "File Storage Path" below

---

Structured Data Path

Modern Apps (iOS 17+)

// ✅ CORRECT: SwiftData for modern structured persistence
import SwiftData

@Model
class Task {
    var title: String
    var isCompleted: Bool
    var dueDate: Date

    init(title: String, isCompleted: Bool = false, dueDate: Date) {
        self.title = title
        self.isCompleted = isCompleted
        self.dueDate = dueDate
    }
}

// Query with type safety
@Query(sort: \Task.dueDate) var tasks: [Task]

Why SwiftData:

• Modern Swift-native API (no Objective-C)
• Type-safe queries
• Built-in CloudKit sync support
• Observable models integrate with SwiftUI
• Use skill: axiom-swiftdata for implementation details

When NOT to use SwiftData:

• Need advanced SQLite features (FTS5, complex joins)
• Existing Core Data app (migration overhead)
• Ultra-performance-critical (direct SQLite is faster)

Advanced Control Needed

// ✅ CORRECT: SQLiteData or GRDB for advanced features
import SQLiteData

// Full-text search, custom indices, raw SQL when needed
let results = try db.prepare("SELECT * FROM users WHERE name MATCH ?", "John")

Use SQLiteData when:

• Need full-text search (FTS5)
• Custom SQL queries and indices
• Maximum performance (direct SQLite)
• Migration from existing SQLite database
• Use skill: axiom-sqlitedata for modern SQLite patterns

Use GRDB when:

• Need reactive queries (ValueObservation)
• Complex database operations
• Type-safe query builders
• Use skill: axiom-grdb for advanced patterns

Legacy Apps (iOS 16 and earlier)

// ❌ LEGACY: Core Data (avoid for new projects)
import CoreData

// NSManagedObject, NSFetchRequest, NSPredicate...

Only use Core Data if:

• Maintaining existing Core Data app
• Can't upgrade to iOS 17 minimum deployment

---

File Storage Path

Decision Tree for Files

What kind of file is it?

├─ USER-CREATED CONTENT (documents, photos created by user)
│   Where: Documents/ directory
│   Backed up: ✅ Yes (iCloud/iTunes)
│   Purged: ❌ Never
│   Visible in Files app: ✅ Yes
│   Example: User's edited photos, documents, exported data
│   → See "Documents Directory" section below
│
├─ APP-GENERATED DATA (not user-visible, must persist)
│   Where: Library/Application Support/
│   Backed up: ✅ Yes
│   Purged: ❌ Never
│   Visible in Files app: ❌ No
│   Example: Database files, user settings, downloaded assets
│   → See "Application Support Directory" section below
│
├─ RE-DOWNLOADABLE / REGENERABLE CONTENT
│   Where: Library/Caches/
│   Backed up: ❌ No (set isExcludedFromBackup)
│   Purged: ✅ Yes (under storage pressure)
│   Example: Thumbnails, API responses, downloaded images
│   → See "Caches Directory" section below
│
└─ TEMPORARY FILES (can be deleted anytime)
    Where: tmp/
    Backed up: ❌ No
    Purged: ✅ Yes (aggressive, even while app running)
    Example: Image processing intermediates, export staging
    → See "Temporary Directory" section below

Documents Directory

// ✅ CORRECT: User-created content in Documents
func saveUserDocument(_ data: Data, filename: String) throws {
    let documentsURL = FileManager.default.urls(
        for: .documentDirectory,
        in: .userDomainMask
    )[0]

    let fileURL = documentsURL.appendingPathComponent(filename)

    // Enable file protection
    try data.write(to: fileURL, options: .completeFileProtection)
}

Key rules:

• ✅ DO store: User-created documents, exported files, user-visible content
• ❌ DON'T store: Downloaded data that can be re-fetched, caches, temp files
• ⚠️ WARNING: Everything here is backed up to iCloud. Large re-downloadable files will bloat backups and may get your app rejected.

Use skill: axiom-file-protection-ref for encryption options

Application Support Directory

// ✅ CORRECT: App data in Application Support
func getAppDataURL() -> URL {
    let appSupportURL = FileManager.default.urls(
        for: .applicationSupportDirectory,
        in: .userDomainMask
    )[0]

    // Create app-specific subdirectory
    let appDataURL = appSupportURL.appendingPathComponent(
        Bundle.main.bundleIdentifier ?? "AppData"
    )

    try? FileManager.default.createDirectory(
        at: appDataURL,
        withIntermediateDirectories: true
    )

    return appDataURL
}

Use for:

• SwiftData/SQLite database files
• User preferences
• Downloaded assets that must persist
• Configuration files

Caches Directory

// ✅ CORRECT: Re-downloadable content in Caches
func cacheDownloadedImage(data: Data, for url: URL) throws {
    let cacheURL = FileManager.default.urls(
        for: .cachesDirectory,
        in: .userDomainMask
    )[0]

    let filename = url.lastPathComponent
    let fileURL = cacheURL.appendingPathComponent(filename)

    try data.write(to: fileURL)

    // Mark as excluded from backup (explicit, though Caches is auto-excluded)
    var resourceValues = URLResourceValues()
    resourceValues.isExcludedFromBackup = true
    try fileURL.setResourceValues(resourceValues)
}

Key rules:

• ✅ The system CAN and WILL delete files here under storage pressure
• ✅ Always have a way to re-download or regenerate
• ❌ Don't store anything that can't be recreated

Use skill: axiom-storage-management-ref for purge policies and disk space management

Temporary Directory

// ✅ CORRECT: Truly temporary files in tmp
func processImageWithTempFile(image: UIImage) throws {
    let tmpURL = FileManager.default.temporaryDirectory
    let tempFileURL = tmpURL.appendingPathComponent(UUID().uuidString + ".jpg")

    // Write temp file
    try image.jpegData(compressionQuality: 0.8)?