appiq-solution 1.1.0 → 1.3.0

package/flutter/punkt.claude/New Folder With Items/commands/feature-data-layer.md

@@ -0,0 +1,924 @@
+# Data Layer Development Command
+
+Develops the data layer (Models, Repository Implementations, Data Sources) for a feature following VoicePilot architectural patterns.
+
+**Usage:** `feature-data-layer [FEATURE_NAME] [FEATURE_DESCRIPTION]`
+
+**Example:** `feature-data-layer project-favorites "Allow users to mark projects as favorites and view them in a separate list"`
+
+## Pre-Execution Checklist
+
+1. **Check Channel Status**: Read `/Users/vapps-it/Projects/voicepilot/.claude/channel.md`
+2. **Verify Dependencies**: Ensure domain layer is completed
+3. **Update Channel**: Mark Data Layer status as "IN_PROGRESS" and assign agent
+4. **Check Blockers**: Verify domain layer provides all necessary interfaces
+
+## Implementation Process
+
+### Phase 1: Analysis & Planning
+
+1. **Study Existing Data Patterns**:
+   - Analyze `lib/data/repositories/` implementation patterns
+   - Study existing model structure in `lib/data/models/`
+   - Review data source patterns and API integration
+   - Check BaseRepository and BaseDataSource usage
+   - Understand JSON serialization and caching patterns
+
+2. **Define Data Requirements**:
+   - Plan API endpoints and data structures
+   - Design caching strategy and offline support
+   - Define model serialization requirements
+   - Plan error handling and fallback mechanisms
+   - Identify external service integrations
+
+3. **Update Channel**: Add data layer requirements to channel.md
+
+### Phase 2: Model Implementation
+
+1. **Create Model File** (`lib/data/models/[feature]_model.dart`):
+   ```dart
+   import 'package:projectpilot/domain/entities/[feature]_entity.dart';
+   
+   class [FeatureName]Model extends [FeatureName]Entity {
+     const [FeatureName]Model({
+       required super.id,
+       required super.title,
+       super.description,
+       required super.createdAt,
+       required super.updatedAt,
+       super.isActive,
+       super.metadata,
+     });
+     
+     /// Create model from entity
+     factory [FeatureName]Model.fromEntity([FeatureName]Entity entity) {
+       return [FeatureName]Model(
+         id: entity.id,
+         title: entity.title,
+         description: entity.description,
+         createdAt: entity.createdAt,
+         updatedAt: entity.updatedAt,
+         isActive: entity.isActive,
+         metadata: entity.metadata,
+       );
+     }
+     
+     /// Create model from JSON (API response)
+     factory [FeatureName]Model.fromJson(Map<String, dynamic> json) {
+       return [FeatureName]Model(
+         id: json['id'] as String,
+         title: json['title'] as String,
+         description: json['description'] as String?,
+         createdAt: DateTime.parse(json['created_at'] as String),
+         updatedAt: DateTime.parse(json['updated_at'] as String),
+         isActive: json['is_active'] as bool? ?? true,
+         metadata: json['metadata'] as Map<String, dynamic>?,
+       );
+     }
+     
+     /// Create model from cache JSON (optimized for local storage)
+     factory [FeatureName]Model.fromCacheJson(Map<String, dynamic> json) {
+       return [FeatureName]Model(
+         id: json['id'] as String,
+         title: json['title'] as String,
+         description: json['description'] as String?,
+         createdAt: DateTime.fromMillisecondsSinceEpoch(
+           json['created_at'] as int,
+         ),
+         updatedAt: DateTime.fromMillisecondsSinceEpoch(
+           json['updated_at'] as int,
+         ),
+         isActive: json['is_active'] as bool? ?? true,
+         metadata: json['metadata'] as Map<String, dynamic>?,
+       );
+     }
+     
+     /// Convert to JSON for API requests
+     Map<String, dynamic> toJson() {
+       return {
+         'id': id,
+         'title': title,
+         'description': description,
+         'created_at': createdAt.toIso8601String(),
+         'updated_at': updatedAt.toIso8601String(),
+         'is_active': isActive,
+         'metadata': metadata,
+       };
+     }
+     
+     /// Convert to cache JSON (optimized for local storage)
+     Map<String, dynamic> toCacheJson() {
+       return {
+         'id': id,
+         'title': title,
+         'description': description,
+         'created_at': createdAt.millisecondsSinceEpoch,
+         'updated_at': updatedAt.millisecondsSinceEpoch,
+         'is_active': isActive,
+         'metadata': metadata,
+       };
+     }
+     
+     /// Convert to entity
+     [FeatureName]Entity toEntity() {
+       return [FeatureName]Entity(
+         id: id,
+         title: title,
+         description: description,
+         createdAt: createdAt,
+         updatedAt: updatedAt,
+         isActive: isActive,
+         metadata: metadata,
+       );
+     }
+     
+     /// Convert to create request JSON
+     Map<String, dynamic> toCreateJson() {
+       return {
+         'title': title,
+         'description': description,
+         'is_active': isActive,
+         'metadata': metadata,
+       };
+     }
+     
+     /// Convert to update request JSON
+     Map<String, dynamic> toUpdateJson() {
+       return {
+         'title': title,
+         'description': description,
+         'is_active': isActive,
+         'metadata': metadata,
+       };
+     }
+     
+     /// Create copyWith method for model
+     @override
+     [FeatureName]Model copyWith({
+       String? id,
+       String? title,
+       String? description,
+       DateTime? createdAt,
+       DateTime? updatedAt,
+       bool? isActive,
+       Map<String, dynamic>? metadata,
+     }) {
+       return [FeatureName]Model(
+         id: id ?? this.id,
+         title: title ?? this.title,
+         description: description ?? this.description,
+         createdAt: createdAt ?? this.createdAt,
+         updatedAt: updatedAt ?? this.updatedAt,
+         isActive: isActive ?? this.isActive,
+         metadata: metadata ?? this.metadata,
+       );
+     }
+   }
+   
+   /// Extension for List<[FeatureName]Model> conversions
+   extension [FeatureName]ModelList on List<[FeatureName]Model> {
+     List<[FeatureName]Entity> toEntityList() {
+       return map((model) => model.toEntity()).toList();
+     }
+     
+     List<Map<String, dynamic>> toCacheJsonList() {
+       return map((model) => model.toCacheJson()).toList();
+     }
+   }
+   
+   /// Extension for List<Map<String, dynamic>> conversions
+   extension [FeatureName]JsonList on List<Map<String, dynamic>> {
+     List<[FeatureName]Model> to[FeatureName]ModelList() {
+       return map((json) => [FeatureName]Model.fromJson(json)).toList();
+     }
+     
+     List<[FeatureName]Model> toCached[FeatureName]ModelList() {
+       return map((json) => [FeatureName]Model.fromCacheJson(json)).toList();
+     }
+   }
+   ```
+
+### Phase 3: Data Source Implementation
+
+1. **Create Remote Data Source** (`lib/data/datasources/[feature]_remote_data_source.dart`):
+   ```dart
+   import 'package:dartz/dartz.dart';
+   import 'package:projectpilot/core/services/base_data_source.dart';
+   import 'package:projectpilot/data/models/[feature]_model.dart';
+   import 'package:projectpilot/domain/failure/failures.dart';
+   
+   abstract class [FeatureName]RemoteDataSource {
+     Future<List<[FeatureName]Model>> getItems({
+       int page = 1,
+       int limit = 20,
+     });
+     
+     Future<[FeatureName]Model> getItemById(String itemId);
+     
+     Future<[FeatureName]Model> createItem(Map<String, dynamic> itemData);
+     
+     Future<[FeatureName]Model> updateItem(String itemId, Map<String, dynamic> itemData);
+     
+     Future<void> deleteItem(String itemId);
+     
+     Future<List<[FeatureName]Model>> searchItems(String query, {int limit = 20});
+     
+     Future<List<[FeatureName]Model>> filterItems({
+       bool? isActive,
+       DateTime? createdAfter,
+       DateTime? createdBefore,
+       Map<String, dynamic>? customFilters,
+     });
+     
+     Future<Map<String, dynamic>> getStatistics();
+   }
+   
+   class [FeatureName]RemoteDataSourceImpl extends BaseDataSource 
+       implements [FeatureName]RemoteDataSource {
+     
+     static const String _baseEndpoint = '/api/v1/[feature-name]';
+     
+     @override
+     Future<List<[FeatureName]Model>> getItems({
+       int page = 1,
+       int limit = 20,
+     }) async {
+       return executeWithErrorHandling(
+         () async {
+           final response = await apiClient.get(
+             '$_baseEndpoint',
+             queryParameters: {
+               'page': page,
+               'limit': limit,
+             },
+           );
+           
+           final data = response.data as Map<String, dynamic>;
+           final items = data['data'] as List<dynamic>;
+           
+           return items
+               .cast<Map<String, dynamic>>()
+               .to[FeatureName]ModelList();
+         },
+         operationName: 'getItems',
+         failureMessage: 'Failed to load items',
+       ).then((either) => either.fold(
+         (failure) => throw failure,
+         (items) => items,
+       ));
+     }
+     
+     @override
+     Future<[FeatureName]Model> getItemById(String itemId) async {
+       return executeWithErrorHandling(
+         () async {
+           final response = await apiClient.get('$_baseEndpoint/$itemId');
+           final data = response.data as Map<String, dynamic>;
+           return [FeatureName]Model.fromJson(data['data']);
+         },
+         operationName: 'getItemById_$itemId',
+         failureMessage: 'Failed to load item',
+       ).then((either) => either.fold(
+         (failure) => throw failure,
+         (item) => item,
+       ));
+     }
+     
+     @override
+     Future<[FeatureName]Model> createItem(Map<String, dynamic> itemData) async {
+       return executeWithErrorHandling(
+         () async {
+           final response = await apiClient.post(
+             _baseEndpoint,
+             data: itemData,
+           );
+           
+           final data = response.data as Map<String, dynamic>;
+           return [FeatureName]Model.fromJson(data['data']);
+         },
+         operationName: 'createItem',
+         failureMessage: 'Failed to create item',
+       ).then((either) => either.fold(
+         (failure) => throw failure,
+         (item) => item,
+       ));
+     }
+     
+     @override
+     Future<[FeatureName]Model> updateItem(
+       String itemId,
+       Map<String, dynamic> itemData,
+     ) async {
+       return executeWithErrorHandling(
+         () async {
+           final response = await apiClient.put(
+             '$_baseEndpoint/$itemId',
+             data: itemData,
+           );
+           
+           final data = response.data as Map<String, dynamic>;
+           return [FeatureName]Model.fromJson(data['data']);
+         },
+         operationName: 'updateItem_$itemId',
+         failureMessage: 'Failed to update item',
+       ).then((either) => either.fold(
+         (failure) => throw failure,
+         (item) => item,
+       ));
+     }
+     
+     @override
+     Future<void> deleteItem(String itemId) async {
+       return executeWithErrorHandling(
+         () async {
+           await apiClient.delete('$_baseEndpoint/$itemId');
+         },
+         operationName: 'deleteItem_$itemId',
+         failureMessage: 'Failed to delete item',
+       ).then((either) => either.fold(
+         (failure) => throw failure,
+         (_) => null,
+       ));
+     }
+     
+     @override
+     Future<List<[FeatureName]Model>> searchItems(
+       String query, {
+       int limit = 20,
+     }) async {
+       return executeWithErrorHandling(
+         () async {
+           final response = await apiClient.get(
+             '$_baseEndpoint/search',
+             queryParameters: {
+               'q': query,
+               'limit': limit,
+             },
+           );
+           
+           final data = response.data as Map<String, dynamic>;
+           final items = data['data'] as List<dynamic>;
+           
+           return items
+               .cast<Map<String, dynamic>>()
+               .to[FeatureName]ModelList();
+         },
+         operationName: 'searchItems_$query',
+         failureMessage: 'Failed to search items',
+       ).then((either) => either.fold(
+         (failure) => throw failure,
+         (items) => items,
+       ));
+     }
+     
+     @override
+     Future<List<[FeatureName]Model>> filterItems({
+       bool? isActive,
+       DateTime? createdAfter,
+       DateTime? createdBefore,
+       Map<String, dynamic>? customFilters,
+     }) async {
+       return executeWithErrorHandling(
+         () async {
+           final queryParameters = <String, dynamic>{};
+           
+           if (isActive != null) queryParameters['is_active'] = isActive;
+           if (createdAfter != null) {
+             queryParameters['created_after'] = createdAfter.toIso8601String();
+           }
+           if (createdBefore != null) {
+             queryParameters['created_before'] = createdBefore.toIso8601String();
+           }
+           if (customFilters != null) {
+             queryParameters.addAll(customFilters);
+           }
+           
+           final response = await apiClient.get(
+             '$_baseEndpoint/filter',
+             queryParameters: queryParameters,
+           );
+           
+           final data = response.data as Map<String, dynamic>;
+           final items = data['data'] as List<dynamic>;
+           
+           return items
+               .cast<Map<String, dynamic>>()
+               .to[FeatureName]ModelList();
+         },
+         operationName: 'filterItems',
+         failureMessage: 'Failed to filter items',
+       ).then((either) => either.fold(
+         (failure) => throw failure,
+         (items) => items,
+       ));
+     }
+     
+     @override
+     Future<Map<String, dynamic>> getStatistics() async {
+       return executeWithErrorHandling(
+         () async {
+           final response = await apiClient.get('$_baseEndpoint/statistics');
+           return response.data as Map<String, dynamic>;
+         },
+         operationName: 'getStatistics',
+         failureMessage: 'Failed to load statistics',
+       ).then((either) => either.fold(
+         (failure) => throw failure,
+         (stats) => stats,
+       ));
+     }
+   }
+   ```
+
+2. **Create Local Data Source** (`lib/data/datasources/[feature]_local_data_source.dart`):
+   ```dart
+   import 'dart:convert';
+   import 'package:shared_preferences/shared_preferences.dart';
+   import 'package:projectpilot/data/models/[feature]_model.dart';
+   
+   abstract class [FeatureName]LocalDataSource {
+     Future<List<[FeatureName]Model>> getCachedItems();
+     Future<void> cacheItems(List<[FeatureName]Model> items);
+     Future<[FeatureName]Model?> getCachedItemById(String itemId);
+     Future<void> cacheItem([FeatureName]Model item);
+     Future<void> removeCachedItem(String itemId);
+     Future<void> clearCache();
+     Future<bool> hasCachedData();
+     Future<DateTime?> getLastCacheTime();
+     Future<void> saveState(dynamic state);
+     Future<dynamic> restoreState();
+   }
+   
+   class [FeatureName]LocalDataSourceImpl implements [FeatureName]LocalDataSource {
+     static const String _cacheKey = '[feature_name]_cache';
+     static const String _cacheTimeKey = '[feature_name]_cache_time';
+     static const String _stateKey = '[feature_name]_state';
+     
+     final SharedPreferences _prefs;
+     
+     const [FeatureName]LocalDataSourceImpl({
+       required SharedPreferences prefs,
+     }) : _prefs = prefs;
+     
+     @override
+     Future<List<[FeatureName]Model>> getCachedItems() async {
+       try {
+         final cachedData = _prefs.getString(_cacheKey);
+         if (cachedData == null) return [];
+         
+         final List<dynamic> jsonList = json.decode(cachedData);
+         return jsonList
+             .cast<Map<String, dynamic>>()
+             .toCached[FeatureName]ModelList();
+       } catch (e) {
+         logger.e('Error loading cached items: $e');
+         return [];
+       }
+     }
+     
+     @override
+     Future<void> cacheItems(List<[FeatureName]Model> items) async {
+       try {
+         final jsonData = json.encode(items.toCacheJsonList());
+         await _prefs.setString(_cacheKey, jsonData);
+         await _prefs.setInt(
+           _cacheTimeKey,
+           DateTime.now().millisecondsSinceEpoch,
+         );
+         logger.d('Cached ${items.length} items');
+       } catch (e) {
+         logger.e('Error caching items: $e');
+       }
+     }
+     
+     @override
+     Future<[FeatureName]Model?> getCachedItemById(String itemId) async {
+       try {
+         final cachedItems = await getCachedItems();
+         return cachedItems.cast<[FeatureName]Model?>().firstWhere(
+           (item) => item?.id == itemId,
+           orElse: () => null,
+         );
+       } catch (e) {
+         logger.e('Error loading cached item: $e');
+         return null;
+       }
+     }
+     
+     @override
+     Future<void> cacheItem([FeatureName]Model item) async {
+       try {
+         final cachedItems = await getCachedItems();
+         final existingIndex = cachedItems.indexWhere((i) => i.id == item.id);
+         
+         if (existingIndex >= 0) {
+           cachedItems[existingIndex] = item;
+         } else {
+           cachedItems.add(item);
+         }
+         
+         await cacheItems(cachedItems);
+       } catch (e) {
+         logger.e('Error caching single item: $e');
+       }
+     }
+     
+     @override
+     Future<void> removeCachedItem(String itemId) async {
+       try {
+         final cachedItems = await getCachedItems();
+         cachedItems.removeWhere((item) => item.id == itemId);
+         await cacheItems(cachedItems);
+       } catch (e) {
+         logger.e('Error removing cached item: $e');
+       }
+     }
+     
+     @override
+     Future<void> clearCache() async {
+       try {
+         await _prefs.remove(_cacheKey);
+         await _prefs.remove(_cacheTimeKey);
+         logger.d('Cache cleared');
+       } catch (e) {
+         logger.e('Error clearing cache: $e');
+       }
+     }
+     
+     @override
+     Future<bool> hasCachedData() async {
+       return _prefs.containsKey(_cacheKey);
+     }
+     
+     @override
+     Future<DateTime?> getLastCacheTime() async {
+       final timestamp = _prefs.getInt(_cacheTimeKey);
+       if (timestamp == null) return null;
+       return DateTime.fromMillisecondsSinceEpoch(timestamp);
+     }
+     
+     @override
+     Future<void> saveState(dynamic state) async {
+       try {
+         final stateJson = json.encode(state);
+         await _prefs.setString(_stateKey, stateJson);
+       } catch (e) {
+         logger.e('Error saving state: $e');
+       }
+     }
+     
+     @override
+     Future<dynamic> restoreState() async {
+       try {
+         final stateData = _prefs.getString(_stateKey);
+         if (stateData == null) return null;
+         return json.decode(stateData);
+       } catch (e) {
+         logger.e('Error restoring state: $e');
+         return null;
+       }
+     }
+   }
+   ```
+
+### Phase 4: Repository Implementation
+
+1. **Create Repository Implementation** (`lib/data/repositories/[feature]_repository_impl.dart`):
+   ```dart
+   import 'package:dartz/dartz.dart';
+   import 'package:projectpilot/core/repositories/base_repository.dart';
+   import 'package:projectpilot/data/datasources/[feature]_local_data_source.dart';
+   import 'package:projectpilot/data/datasources/[feature]_remote_data_source.dart';
+   import 'package:projectpilot/data/models/[feature]_model.dart';
+   import 'package:projectpilot/domain/entities/[feature]_entity.dart';
+   import 'package:projectpilot/domain/failure/failures.dart';
+   import 'package:projectpilot/domain/repositories/[feature]_repository.dart';
+   
+   class [FeatureName]RepositoryImpl extends BaseRepository 
+       implements [FeatureName]Repository {
+     final [FeatureName]RemoteDataSource _remoteDataSource;
+     final [FeatureName]LocalDataSource _localDataSource;
+     
+     const [FeatureName]RepositoryImpl({
+       required [FeatureName]RemoteDataSource remoteDataSource,
+       required [FeatureName]LocalDataSource localDataSource,
+     }) : _remoteDataSource = remoteDataSource,
+          _localDataSource = localDataSource;
+     
+     @override
+     Future<Either<Failure, List<[FeatureName]Entity>>> getItems({
+       int page = 1,
+       int limit = 20,
+       bool forceRefresh = false,
+     }) async {
+       return executeSupabaseOperation(
+         () async {
+           // Try remote first, fallback to cache
+           if (!forceRefresh) {
+             final cachedItems = await _localDataSource.getCachedItems();
+             if (cachedItems.isNotEmpty) {
+               logger.d('Returning ${cachedItems.length} cached items');
+               return cachedItems.toEntityList();
+             }
+           }
+           
+           try {
+             final remoteItems = await _remoteDataSource.getItems(
+               page: page,
+               limit: limit,
+             );
+             
+             // Cache the results
+             await _localDataSource.cacheItems(remoteItems);
+             
+             logger.d('Loaded ${remoteItems.length} items from remote');
+             return remoteItems.toEntityList();
+           } catch (e) {
+             // Fallback to cache on network error
+             final cachedItems = await _localDataSource.getCachedItems();
+             if (cachedItems.isNotEmpty) {
+               logger.w('Network failed, returning cached items: $e');
+               return cachedItems.toEntityList();
+             }
+             rethrow;
+           }
+         },
+         operationName: 'getItems_page${page}_limit$limit',
+         failureMessage: 'Failed to load items',
+       );
+     }
+     
+     @override
+     Future<Either<Failure, [FeatureName]Entity>> getItemById(
+       String itemId,
+     ) async {
+       return executeSupabaseOperation(
+         () async {
+           try {
+             final remoteItem = await _remoteDataSource.getItemById(itemId);
+             await _localDataSource.cacheItem(remoteItem);
+             return remoteItem.toEntity();
+           } catch (e) {
+             // Fallback to cache
+             final cachedItem = await _localDataSource.getCachedItemById(itemId);
+             if (cachedItem != null) {
+               logger.w('Network failed, returning cached item: $e');
+               return cachedItem.toEntity();
+             }
+             rethrow;
+           }
+         },
+         operationName: 'getItemById_$itemId',
+         failureMessage: 'Failed to load item',
+       );
+     }
+     
+     @override
+     Future<Either<Failure, [FeatureName]Entity>> createItem({
+       required String title,
+       String? description,
+       Map<String, dynamic>? metadata,
+       Map<String, dynamic>? additionalData,
+     }) async {
+       return executeSupabaseOperation(
+         () async {
+           final itemData = <String, dynamic>{
+             'title': title,
+             'description': description,
+             'metadata': metadata,
+             ...?additionalData,
+           };
+           
+           final createdItem = await _remoteDataSource.createItem(itemData);
+           await _localDataSource.cacheItem(createdItem);
+           
+           logger.d('Created item: ${createdItem.id}');
+           return createdItem.toEntity();
+         },
+         operationName: 'createItem',
+         failureMessage: 'Failed to create item',
+       );
+     }
+     
+     @override
+     Future<Either<Failure, [FeatureName]Entity>> updateItem(
+       [FeatureName]Entity item,
+     ) async {
+       return executeSupabaseOperation(
+         () async {
+           final model = [FeatureName]Model.fromEntity(item);
+           final updatedItem = await _remoteDataSource.updateItem(
+             item.id,
+             model.toUpdateJson(),
+           );
+           
+           await _localDataSource.cacheItem(updatedItem);
+           
+           logger.d('Updated item: ${updatedItem.id}');
+           return updatedItem.toEntity();
+         },
+         operationName: 'updateItem_${item.id}',
+         failureMessage: 'Failed to update item',
+       );
+     }
+     
+     @override
+     Future<Either<Failure, void>> deleteItem(String itemId) async {
+       return executeSupabaseOperation(
+         () async {
+           await _remoteDataSource.deleteItem(itemId);
+           await _localDataSource.removeCachedItem(itemId);
+           
+           logger.d('Deleted item: $itemId');
+         },
+         operationName: 'deleteItem_$itemId',
+         failureMessage: 'Failed to delete item',
+       );
+     }
+     
+     @override
+     Future<Either<Failure, List<[FeatureName]Entity>>> searchItems(
+       String query, {
+       int limit = 20,
+     }) async {
+       return executeSupabaseOperation(
+         () async {
+           final results = await _remoteDataSource.searchItems(
+             query,
+             limit: limit,
+           );
+           
+           logger.d('Search "$query" returned ${results.length} items');
+           return results.toEntityList();
+         },
+         operationName: 'searchItems_$query',
+         failureMessage: 'Failed to search items',
+       );
+     }
+     
+     @override
+     Future<Either<Failure, List<[FeatureName]Entity>>> filterItems({
+       bool? isActive,
+       DateTime? createdAfter,
+       DateTime? createdBefore,
+       List<String>? tags,
+       Map<String, dynamic>? customFilters,
+     }) async {
+       return executeSupabaseOperation(
+         () async {
+           final filters = <String, dynamic>{
+             ...?customFilters,
+           };
+           
+           if (tags != null && tags.isNotEmpty) {
+             filters['tags'] = tags.join(',');
+           }
+           
+           final results = await _remoteDataSource.filterItems(
+             isActive: isActive,
+             createdAfter: createdAfter,
+             createdBefore: createdBefore,
+             customFilters: filters,
+           );
+           
+           logger.d('Filter returned ${results.length} items');
+           return results.toEntityList();
+         },
+         operationName: 'filterItems',
+         failureMessage: 'Failed to filter items',
+       );
+     }
+     
+     @override
+     Future<Either<Failure, List<[FeatureName]Entity>>> getCachedItems() async {
+       return executeSupabaseOperation(
+         () async {
+           final cachedItems = await _localDataSource.getCachedItems();
+           return cachedItems.toEntityList();
+         },
+         operationName: 'getCachedItems',
+         failureMessage: 'Failed to load cached items',
+       );
+     }
+     
+     @override
+     Future<Either<Failure, void>> clearCache() async {
+       return executeSupabaseOperation(
+         () async {
+           await _localDataSource.clearCache();
+           logger.d('Cache cleared');
+         },
+         operationName: 'clearCache',
+         failureMessage: 'Failed to clear cache',
+       );
+     }
+     
+     @override
+     Future<Either<Failure, void>> saveCachedItems(
+       List<[FeatureName]Entity> items,
+     ) async {
+       return executeSupabaseOperation(
+         () async {
+           final models = items
+               .map((entity) => [FeatureName]Model.fromEntity(entity))
+               .toList();
+           await _localDataSource.cacheItems(models);
+         },
+         operationName: 'saveCachedItems',
+         failureMessage: 'Failed to save cached items',
+       );
+     }
+     
+     @override
+     Future<Either<Failure, Map<String, dynamic>>> getStatistics() async {
+       return executeSupabaseOperation(
+         () async {
+           return await _remoteDataSource.getStatistics();
+         },
+         operationName: 'getStatistics',
+         failureMessage: 'Failed to load statistics',
+       );
+     }
+     
+     // Implement all other required methods following the same pattern...
+     // [Additional methods for batch operations, sync, etc.]
+   }
+   ```
+
+## Quality Checklist
+
+### Model Implementation
+- [ ] Extends domain entity correctly
+- [ ] JSON serialization implemented
+- [ ] Cache optimization methods
+- [ ] Conversion methods (toEntity, fromEntity)
+- [ ] List extension methods
+
+### Data Sources
+- [ ] BaseDataSource pattern followed
+- [ ] Comprehensive error handling
+- [ ] Proper logging implementation
+- [ ] Caching strategies implemented
+- [ ] Fallback mechanisms included
+
+### Repository Implementation
+- [ ] BaseRepository pattern followed
+- [ ] Remote/local coordination
+- [ ] Proper error propagation
+- [ ] Either return types used
+- [ ] Cache management implemented
+
+### Performance
+- [ ] Efficient serialization
+- [ ] Optimized caching
+- [ ] Proper resource management
+- [ ] Memory leak prevention
+- [ ] Background operation support
+
+## Channel Communication
+
+### Before Starting
+Update channel.md:
+```markdown
+### 💾 Data Layer Status
+- **Status:** IN_PROGRESS
+- **Assigned Agent:** [YOUR_ID]
+- **Progress:** 0%
+```
+
+### During Development
+Update progress regularly:
+```markdown
+- **Progress:** [PERCENTAGE]%
+- **Files Created:** [LIST_OF_FILES]
+- **Next Steps:** [CURRENT_WORK]
+```
+
+### After Completion
+Mark as completed:
+```markdown
+### 💾 Data Layer Status
+- **Status:** COMPLETED
+- **Progress:** 100%
+- **Files Created:** [COMPLETE_LIST]
+```
+
+## Dependencies
+
+### Must be completed first:
+- Domain layer (entities and repository interfaces)
+
+### Enables after completion:
+- Business logic integration
+- UI layer data binding
+- Full feature integration
+
+## Output Deliverables
+
+1. **Model**: `lib/data/models/[feature]_model.dart`
+2. **Remote Data Source**: `lib/data/datasources/[feature]_remote_data_source.dart`
+3. **Local Data Source**: `lib/data/datasources/[feature]_local_data_source.dart`
+4. **Repository Implementation**: `lib/data/repositories/[feature]_repository_impl.dart`
+5. **Updated Channel**: Progress and completion status in channel.md
+
+All data layer components must follow existing patterns and provide robust caching, error handling, and offline support.