Data Layer Component

1. Requirements Document

Overview

A comprehensive wrapper for managing local data persistence and synchronization. It unifies different local storage engines (SQLite, Hive, SharedPrefs) under a standard repository pattern, supporting reactive updates and offline-first capabilities.

User Stories

As a Developer, I want to save an object and have it automatically update in the UI.
As a Developer, I want to cache API results seamlessly and expire them after a set time.
As a Developer, I want to switch from Hive to SQLite for complex queries without changing the UI code.

Functional Requirements

Unified Storage: A generic interface (LocalSource<T>) for CRUD operations.
Reactive Streams: Watch data changes (listen to db updates) directly from the storage layer.
Caching Strategy: Policies for Write-Through, Read-Through, and Stale-While-Revalidate.
Type Safety: enforced strict typing for stored objects.

2. Technical Document

Architecture

System Architecture

The Data Layer Component acts as the single source of truth for the application's state. By wrapping specific storage implementations, it allows the rest of the app to be agnostic about where data originates (Network vs Disk) or how it is stored.

API Design

Storage Interface

abstract class LocalSource<T> {
  Future<void> put(String key, T item);
  Future<T?> get(String key);
  Stream<T?> watch(String key);
  Future<void> delete(String key);
}

Repository Implementation

class ProductRepository {
  final LocalSource<Product> _local;
  final ApiSource _remote;
 
  Stream<Product> getProduct(String id) async* {
    // 1. Emit local data first (fast)
    final local = await _local.get(id);
    if (local != null) yield local;
 
    // 2. Fetch fresh data
    try {
      final remote = await _remote.fetch(id);
      await _local.put(id, remote); // Update cache
      yield remote;
    } catch (_) {
      // Handle offline case
    }
  }
}