# Charge Curve Storage Operation

Stocarea şi retrieval-ul curbelor de încărcare în persistență.

## Responsabilități

- Persistență curbe în Core Data (sesiuni + measurements)

- Sincronizare curbe în iCloud (CloudKit)

- Compresie date (sampling, agregare)

- Cleanup și archiving sesiuni vechi

## Arhitectură

### Core Data entities

```

ChargeSession

├── id: UUID

├── chargedDeviceID: UUID

├── startTime: Date

├── endTime: Date

├── startBatteryPercent: Double?

├── endBatteryPercent: Double?

├── totalEnergyWh: Double

└── checkpoints: [ChargeCheckpoint]

ChargeCheckpoint (measurement)

├── id: UUID

├── sessionID: UUID

├── timestamp: Date

├── voltage: Double

├── current: Double

├── power: Double

├── temperature: Double?

└── batteryPercent: Double?

```

### Storage layers

1. **In-memory cache**: Recent sessions (last 24h)

2. **Local Core Data**: All sessions

3. **iCloud CloudKit**: Synced sessions (optional, per user)

4. **Archive**: Old sessions (JSON export, local only)

```

Memory cache (24h)

       ↓

   Core Data (local)

   /           \

  ↓             ↓

 iCloud      Archive (JSON)

(CloudKit)   (5+ years old)

```

## Invarianţi

- **MUST**: Fiecare `ChargeSession` are `id` unic

- **MUST**: Fiecare `ChargeCheckpoint` are reference valid la `sessionID`

- **MUST**: Checkpoints ordonate cronologic în sesiune

- **MUST**: `startTime < endTime` pentru completed sessions

- **MUST**: CloudKit sync preserve integrity (no partial sessions)

- **SHOULD**: Sesiuni < 5 minute nu se sincronizează (noise)

- **MAY**: Archive sesiuni > 5 ani local-only

## Save flow

### 1. In-memory accumulation

```swift

let session = meter.startChargeRecord(for: device)

// session object in-memory

// accumulate measurements în session.measurements array

while isCharging {

    let measurement = meter.lastDataPoint

    session.addMeasurement(measurement)  // In-memory

}

```

**Properties:**

- Rapid (no I/O)

- Loss on app crash

- Limits: max 1MB per session (~10k measurements @ 1Hz)

### 2. Flush to Core Data

```swift

func endChargeRecord(_ session: ChargeRecord) {

    // 1. Isolate valid curve

    let isolated = isolateChargeRange(session.measurements)

    // 2. Save to Core Data

    let coreDataSession = ChargeSession()

    coreDataSession.id = session.id

    coreDataSession.chargedDeviceID = device.id

    coreDataSession.startTime = isolated.realStartTime

    coreDataSession.endTime = isolated.realEndTime

    coreDataSession.totalEnergyWh = calculateEnergy(isolated.measurements)

    // 3. Save checkpoints

    for measurement in isolated.measurements {

        let checkpoint = ChargeCheckpoint()

        checkpoint.timestamp = measurement.timestamp

        checkpoint.voltage = measurement.voltage

        checkpoint.current = measurement.current

        checkpoint.power = measurement.power

        // ... other fields

        coreDataSession.checkpoints.append(checkpoint)

    }

    // 4. Persist

    managedObjectContext.insert(coreDataSession)

    try? managedObjectContext.save()

}

```

**Guarantees:**

- ACID transaction

- Survives app crash

- Instantly queryable

### 3. CloudKit sync (async)

```swift

// NSPersistentCloudKitContainer handles automatically

// New/modified ChargeSession → CloudKit

// Happens in background, doesn't block UI

```

**Flow:**

```

Core Data save

  ↓

NSPersistentCloudKitContainer observes change

  ↓

Serializes to CloudKit record

  ↓

Uploads in background (when network available)

  ↓

Notifies on success/failure

```

**CloudSync constraints:**

- **MUST**: Sessions < 5 min nu se syncă (noise filter)

- **MUST**: Checkpoints limitate la max 1000 per CloudKit record

- **SHOULD**: Aggregate samples dacă > 1000 checkpoints

## Load flow

### 1. Query Core Data

```swift

func loadSessions(for device: ChargedDevice) -> [ChargeSession] {

    let request: NSFetchRequest<ChargeSession> = ChargeSession.fetchRequest()

    request.predicate = NSPredicate(format: "chargedDeviceID == %@", device.id as NSUUID)

    request.sortDescriptors = [NSSortDescriptor(key: "startTime", ascending: false)]

    let sessions = try? managedObjectContext.fetch(request)

    return sessions ?? []

}

func loadCheckpoints(for session: ChargeSession) -> [ChargeCheckpoint] {

    let request: NSFetchRequest<ChargeCheckpoint> = ChargeCheckpoint.fetchRequest()

    request.predicate = NSPredicate(format: "sessionID == %@", session.id as NSUUID)

    request.sortDescriptors = [NSSortDescriptor(key: "timestamp", ascending: true)]

    let checkpoints = try? managedObjectContext.fetch(request)

    return checkpoints ?? []

}

```

**Performance:**

- O(log n) for device lookup (indexed)

- O(k) for checkpoint load (k = checkpoint count, typically 1000-5000)

### 2. Reconstruct curve

```swift

func reconstructCurve(from session: ChargeSession) -> ChargeCurve {

    let checkpoints = loadCheckpoints(for: session)

    return ChargeCurve(

        startTime: session.startTime,

        endTime: session.endTime,

        totalEnergy: session.totalEnergyWh,

        measurements: checkpoints.map { cp in

            Measurement(

                timestamp: cp.timestamp,

                voltage: cp.voltage,

                current: cp.current,

                power: cp.power

            )

        }

    )

}

```

### 3. Cache in memory

```swift

// Keep last 24h in cache

var recentCurves: [UUID: ChargeCurve] = [:]

func cachedCurve(for sessionID: UUID) -> ChargeCurve? {

    if let cached = recentCurves[sessionID] {

        return cached  // Memory hit

    }

    // Core Data miss → fetch + cache

    guard let coreDataSession = loadSessionFromCoreData(sessionID) else {

        return nil

    }

    let curve = reconstructCurve(from: coreDataSession)

    recentCurves[sessionID] = curve

    return curve

}

```

## Compression strategies

### For frequent access (last 7 days)

**Store:** All 1Hz measurements

**Cost:** ~1000 checkpoints per session

### For occasional access (7-365 days)

**Strategy:** Downsample to 10Hz

```swift

func downsampleCurve(measurements: [Measurement], factor: Int) -> [Measurement] {

    return measurements.enumerated()

        .filter { $0.offset % factor == 0 }

        .map { $0.element }

}

```

**Reduction:** 10x fewer points

**Loss:** Minimal (still captures curve shape)

**Cost:** ~100 checkpoints per session

### For archive (> 1 year)

**Strategy:** Store metadata only

```swift

struct SessionMetadata {

    let id: UUID

    let chargedDeviceID: UUID

    let startTime: Date

    let endTime: Date

    let totalEnergyWh: Double

    let peakPowerW: Double

    let averagePowerW: Double

    // No measurements stored

}

```

**Cost:** Minimal (constant per session)

**Retrieval:** Summary only, not full curve

## CloudKit constraints

### Record size limits

- CloudKit record: max 4 MB

- Checkpoints JSON: ~100 bytes per checkpoint

- Max checkpoints per record: ~40k

- Typical session: 1000-5000 checkpoints

### Sync strategy

```swift

func syncSessionsToCloudKit() {

    let allSessions = loadSessionsFromCoreData()

    for session in allSessions {

        // Filter: only sessions > 5 minutes

        guard session.duration >= 300 else { continue }

        // Aggregate: if checkpoints > 2000, downsample

        var checkpoints = loadCheckpoints(for: session)

        if checkpoints.count > 2000 {

            checkpoints = downsampleCurve(checkpoints, factor: 2)

        }

        // Push to CloudKit (NSPersistentCloudKitContainer handles)

    }

}

```

**MUST**: Filtrare sesiuni mici (< 5 min)

**SHOULD**: Agregate checkpoint-uri dacă > 2000

**MAY**: Archive > 1 an local-only

## API Public

### Save

```swift

// Save completed session

func saveChargeSession(_ session: ChargeRecord)

// Isolates curve → persists to Core Data → CloudKit async

// Append checkpoint

func appendCheckpoint(_ measurement: Measurement, to sessionID: UUID)

// In-memory only, flushed on session end

```

### Load

```swift

// Query by device

func loadSessions(for device: ChargedDevice) -> [ChargeSession]

// Load single session

func loadSession(id: UUID) -> ChargeSession?

// Load curve with checkpoints

func loadFullCurve(sessionID: UUID) -> ChargeCurve?

// Load metadata only (fast)

func loadSessionMetadata(sessionID: UUID) -> SessionMetadata?

```

### Cleanup

```swift

// Archive old sessions (local)

func archiveOldSessions(olderThan: Date) -> Int

// Returns count archived

// Cleanup from iCloud

func deleteFromCloudKit(sessionID: UUID)

// MUST: permanent (CloudKit deletion, can't undo)

```

## Comportamente critice

### Concurrent saves

```

User: Start session on meter A

App: Saves session A

User: Also start session on meter B

App: Saves session B

⟹ Both saved (transactions independent)

```

**MUST**: Core Data transactions isolate (ACID)

**MUST**: CloudKit syncs maintain order

### CloudKit unavailable

```

Device offline

App saves to Core Data ✓

CloudKit sync queued

User goes online

Sync resumes automatically

⟹ Transparent

```

**MUST**: Queue pending changes

**SHOULD**: Retry with backoff

**MUST**: Persist queue to disk (survive app restart)

### Duplicate on restore

```

Device A: 100 sessions synced to iCloud

User: Restore from backup

Device B: Pulls 100 sessions

Device A: Restarts, sees 100 sessions (already synced)

⟹ Deduplication needed

```

**MUST**: Deduplicate by session ID

**SHOULD**: Keep most recent version

## Testare

### Unit tests

```swift

test_saveSession_PersistsToCoreData()

test_loadSessions_ByDevice()

test_loadCheckpoints_Ordered()

test_downsampleCurve_ReducesFactor()

test_cloudSyncFilters_SessionsUnder5Min()

test_archiveOldSessions_By Date()

test_deduplicateOnRestore()

```

### Integration tests

- [ ] Save session → reload → same data

- [ ] CloudKit sync without network (queued)

- [ ] Resume CloudKit sync when online

- [ ] Downsample 7+ day old sessions

- [ ] Archive 1+ year old sessions

- [ ] Delete from CloudKit (permanent)

## Performance considerations

| Operation | Time | Notes |

|---|---|---|

| Save session | < 100ms | Core Data write |

| Load 100 sessions | < 50ms | Indexed query |

| Load curve (1000 pts) | < 200ms | Reconstruct array |

| CloudKit sync | ~1-5s | Network dependent |

| Downsample 5000 pts | < 20ms | CPU bound |

## Dependenţe

- Core Data: NSManagedObjectContext

- CloudKit: NSPersistentCloudKitContainer

- [Charging Monitoring](./ChargingMonitoring.md): input sessions

- [Charge Curve Isolation](./ChargeCurveIsolation.md): isolated data

- File system: archiving

## References

- [Charge Session Integrity](../Charge%20Session%20Integrity%20and%20Conflict%20Healing.md)

- Core Data Performance Tuning: https://developer.apple.com/videos/play/wwdc2021/10190/

- CloudKit limits: https://developer.apple.com/icloud/cloudkit/