@appiq/flutter-workflow 1.2.0 → 1.3.0

package/templates/additional_data_req.md

@@ -0,0 +1,480 @@
+# Additional Data Requirements - Supabase MCP Integration
+
+This template defines advanced data layer requirements with Supabase MCP integration for automated backend communication and management.
+
+## Supabase MCP Integration
+
+### Automatic Backend Setup
+The Data Agent now includes Supabase MCP integration for seamless backend operations:
+- **Database Schema Creation** - Automatic table and relationship setup
+- **API Generation** - Auto-generated REST and GraphQL endpoints
+- **Authentication Integration** - Built-in user management and session handling
+- **Real-time Subscriptions** - Live data updates and change notifications
+- **File Storage Integration** - Automatic file upload and management
+- **Edge Functions** - Serverless function deployment and management
+
+### MCP Configuration
+```yaml
+# Supabase MCP automatically configured for:
+database:
+  - table_creation: true
+  - relationship_setup: true
+  - index_optimization: true
+  - rls_policies: true
+
+api:
+  - rest_endpoints: auto_generated
+  - graphql_schema: auto_generated
+  - openapi_spec: auto_generated
+
+auth:
+  - user_management: enabled
+  - session_handling: automatic
+  - oauth_providers: configurable
+  - jwt_validation: built_in
+
+realtime:
+  - change_subscriptions: enabled
+  - broadcast_channels: enabled
+  - presence_tracking: enabled
+
+storage:
+  - bucket_management: automatic
+  - file_uploads: integrated
+  - cdn_optimization: enabled
+```
+
+## Advanced Data Layer Patterns
+
+### Real-time Data Synchronization
+```dart
+class {Entity}RealtimeRepository extends {Entity}Repository {
+  final SupabaseClient supabase;
+  final RealtimeChannel? _subscription;
+
+  {Entity}RealtimeRepository({required this.supabase});
+
+  // Automatic real-time subscription setup via MCP
+  Stream<List<{Entity}>> watchEntities() {
+    return supabase
+        .from('{entity_table}')
+        .stream(primaryKey: ['id'])
+        .map((data) => data.map((json) => {Entity}.fromJson(json)).toList());
+  }
+
+  // Real-time updates with optimistic UI
+  Future<Either<Failure, {Entity}>> updateWithRealtime({Entity} entity) async {
+    try {
+      // MCP handles optimistic updates and conflict resolution
+      final response = await supabase
+          .from('{entity_table}')
+          .update(entity.toJson())
+          .eq('id', entity.id)
+          .select();
+
+      if (response.isEmpty) {
+        return Left(DataFailure('Update failed'));
+      }
+
+      return Right({Entity}.fromJson(response.first));
+    } catch (e) {
+      return Left(DataFailure(e.toString()));
+    }
+  }
+}
+```
+
+### Automated Database Migrations
+```dart
+// MCP automatically handles database schema changes
+class DatabaseMigrationManager {
+  final SupabaseClient supabase;
+
+  // MCP integration for automatic migrations
+  Future<void> runMigrations() async {
+    // Supabase MCP automatically:
+    // 1. Detects schema changes in entities
+    // 2. Generates migration scripts
+    // 3. Applies migrations safely
+    // 4. Updates API endpoints
+    // 5. Refreshes client SDKs
+    
+    await supabase.rpc('apply_automatic_migrations');
+  }
+}
+```
+
+### Advanced Query Optimization
+```dart
+class OptimizedQueryRepository {
+  final SupabaseClient supabase;
+
+  // MCP-optimized complex queries
+  Future<Either<Failure, List<{Entity}>>> getEntitiesWithRelations({
+    required QueryParams params,
+  }) async {
+    try {
+      // MCP automatically optimizes:
+      // - Join operations
+      // - Index usage
+      // - Query planning
+      // - Result caching
+      
+      final query = supabase
+          .from('{entity_table}')
+          .select('''
+            *,
+            related_table!inner(*),
+            nested_relation(*)
+          ''');
+
+      // Apply filters with MCP optimization
+      if (params.filters.isNotEmpty) {
+        for (final filter in params.filters) {
+          query.filter(filter.column, filter.operator, filter.value);
+        }
+      }
+
+      // MCP handles pagination and sorting
+      final response = await query
+          .range(params.offset, params.offset + params.limit)
+          .order(params.sortBy, ascending: params.ascending);
+
+      return Right(
+        response.map((json) => {Entity}.fromJson(json)).toList(),
+      );
+    } catch (e) {
+      return Left(DataFailure('Query failed: ${e.toString()}'));
+    }
+  }
+}
+```
+
+## File Storage Integration
+
+### Automatic File Management
+```dart
+class {Entity}StorageRepository {
+  final SupabaseClient supabase;
+  
+  // MCP-managed file operations
+  Future<Either<Failure, String>> uploadFile({
+    required File file,
+    required String bucket,
+    String? path,
+  }) async {
+    try {
+      // MCP automatically handles:
+      // - File validation and processing
+      // - Thumbnail generation
+      // - Compression optimization
+      // - CDN distribution
+      // - Security scanning
+      
+      final fileName = path ?? '${DateTime.now().millisecondsSinceEpoch}_${file.path.split('/').last}';
+      
+      await supabase.storage
+          .from(bucket)
+          .upload(fileName, file);
+
+      // Get public URL with CDN optimization
+      final publicUrl = supabase.storage
+          .from(bucket)
+          .getPublicUrl(fileName);
+
+      return Right(publicUrl);
+    } catch (e) {
+      return Left(StorageFailure(e.toString()));
+    }
+  }
+
+  // Automatic file cleanup and lifecycle management
+  Future<Either<Failure, void>> cleanupOrphanedFiles() async {
+    try {
+      // MCP automatically identifies and removes unused files
+      await supabase.rpc('cleanup_orphaned_files');
+      return const Right(null);
+    } catch (e) {
+      return Left(StorageFailure(e.toString()));
+    }
+  }
+}
+```
+
+## Authentication & Security Integration
+
+### Automatic User Management
+```dart
+class AuthRepository {
+  final SupabaseClient supabase;
+
+  // MCP-integrated authentication
+  Future<Either<Failure, User>> signUpWithEmail({
+    required String email,
+    required String password,
+    Map<String, dynamic>? metadata,
+  }) async {
+    try {
+      // MCP automatically handles:
+      // - Email validation and verification
+      // - Password strength enforcement
+      // - Rate limiting and security
+      // - User profile creation
+      // - Welcome email sequences
+      
+      final response = await supabase.auth.signUp(
+        email: email,
+        password: password,
+        data: metadata,
+      );
+
+      if (response.user == null) {
+        return Left(AuthFailure('Sign up failed'));
+      }
+
+      return Right(User.fromSupabaseUser(response.user!));
+    } catch (e) {
+      return Left(AuthFailure(e.toString()));
+    }
+  }
+
+  // Automatic session management
+  Stream<AuthState> watchAuthState() {
+    return supabase.auth.onAuthStateChange.map((event) {
+      return AuthState.fromSupabaseAuthState(event);
+    });
+  }
+}
+```
+
+### Row Level Security (RLS) Integration
+```dart
+// MCP automatically configures RLS policies
+class SecureDataRepository {
+  final SupabaseClient supabase;
+
+  // Queries automatically respect RLS policies
+  Future<Either<Failure, List<{Entity}>>> getUserEntities() async {
+    try {
+      // MCP automatically:
+      // - Applies user-specific RLS policies
+      // - Validates permissions
+      // - Logs access attempts
+      // - Handles multi-tenant data isolation
+      
+      final response = await supabase
+          .from('{entity_table}')
+          .select()
+          .eq('user_id', supabase.auth.currentUser?.id);
+
+      return Right(
+        response.map((json) => {Entity}.fromJson(json)).toList(),
+      );
+    } catch (e) {
+      return Left(SecurityFailure(e.toString()));
+    }
+  }
+}
+```
+
+## Edge Functions Integration
+
+### Automatic Function Deployment
+```dart
+class EdgeFunctionRepository {
+  final SupabaseClient supabase;
+
+  // MCP-deployed edge functions
+  Future<Either<Failure, T>> callEdgeFunction<T>({
+    required String functionName,
+    required Map<String, dynamic> payload,
+    required T Function(Map<String, dynamic>) fromJson,
+  }) async {
+    try {
+      // MCP automatically:
+      // - Deploys functions based on use case definitions
+      // - Handles authentication and authorization
+      // - Manages function versioning
+      // - Provides monitoring and logging
+      
+      final response = await supabase.functions.invoke(
+        functionName,
+        body: payload,
+      );
+
+      if (response.data == null) {
+        return Left(FunctionFailure('Function call failed'));
+      }
+
+      return Right(fromJson(response.data));
+    } catch (e) {
+      return Left(FunctionFailure(e.toString()));
+    }
+  }
+}
+```
+
+## Offline-First with Sync
+
+### Automatic Data Synchronization
+```dart
+class OfflineFirstRepository extends {Entity}Repository {
+  final SupabaseClient supabase;
+  final LocalDatabase localDb;
+
+  // MCP-managed offline/online sync
+  Future<Either<Failure, List<{Entity}>>> getEntitiesOfflineFirst() async {
+    try {
+      // 1. Return local data immediately
+      final localData = await localDb.getEntities();
+      
+      // 2. MCP automatically syncs in background
+      _syncWithSupabase();
+      
+      return Right(localData);
+    } catch (e) {
+      return Left(DataFailure(e.toString()));
+    }
+  }
+
+  Future<void> _syncWithSupabase() async {
+    // MCP handles:
+    // - Conflict resolution
+    // - Delta synchronization
+    // - Connection state management
+    // - Retry logic with exponential backoff
+    
+    await supabase.rpc('sync_offline_data', params: {
+      'last_sync': await localDb.getLastSyncTime(),
+      'local_changes': await localDb.getPendingChanges(),
+    });
+  }
+}
+```
+
+## Performance Optimization
+
+### Automatic Caching & CDN
+```dart
+class CachedDataRepository {
+  final SupabaseClient supabase;
+  final CacheManager cache;
+
+  Future<Either<Failure, List<{Entity}>>> getCachedEntities() async {
+    try {
+      // MCP automatically:
+      // - Implements intelligent caching strategies
+      // - Manages cache invalidation
+      // - Distributes via CDN
+      // - Compresses responses
+      // - Handles cache warming
+      
+      final cacheKey = 'entities_${DateTime.now().day}';
+      
+      // Check cache first
+      final cached = await cache.get(cacheKey);
+      if (cached != null) {
+        return Right(cached);
+      }
+
+      // Fetch from Supabase with MCP optimizations
+      final response = await supabase
+          .from('{entity_table}')
+          .select()
+          .withCount();
+
+      final entities = response.map((json) => {Entity}.fromJson(json)).toList();
+      
+      // Cache with MCP-determined TTL
+      await cache.set(cacheKey, entities);
+      
+      return Right(entities);
+    } catch (e) {
+      return Left(DataFailure(e.toString()));
+    }
+  }
+}
+```
+
+## Analytics & Monitoring
+
+### Automatic Performance Tracking
+```dart
+class AnalyticsRepository {
+  final SupabaseClient supabase;
+
+  // MCP automatically tracks:
+  // - Query performance
+  // - Error rates
+  // - User behavior
+  // - System usage
+  // - Cost optimization opportunities
+  
+  Future<void> trackUserAction({
+    required String action,
+    Map<String, dynamic>? metadata,
+  }) async {
+    // Automatic analytics via MCP
+    await supabase.rpc('track_analytics_event', params: {
+      'event_name': action,
+      'user_id': supabase.auth.currentUser?.id,
+      'metadata': metadata,
+      'timestamp': DateTime.now().toIso8601String(),
+    });
+  }
+}
+```
+
+## Implementation Checklist
+
+### Supabase MCP Setup
+- [ ] Supabase project configured with MCP integration
+- [ ] Database schema automatically generated from entities
+- [ ] API endpoints auto-generated with proper typing
+- [ ] Authentication and session management configured
+- [ ] Real-time subscriptions enabled
+- [ ] File storage buckets and policies setup
+- [ ] Edge functions deployed for business logic
+
+### Data Layer Implementation
+- [ ] Repository implementations with Supabase MCP integration
+- [ ] Real-time data synchronization patterns
+- [ ] Offline-first architecture with automatic sync
+- [ ] File upload and management integration
+- [ ] Authentication state management
+- [ ] Row-level security and permission handling
+
+### Performance & Monitoring
+- [ ] Automatic caching and CDN configuration
+- [ ] Query optimization and performance monitoring
+- [ ] Error tracking and logging setup
+- [ ] Analytics and user behavior tracking
+- [ ] Cost optimization and usage monitoring
+- [ ] Automated backup and disaster recovery
+
+### Security & Compliance
+- [ ] Row-level security policies configured
+- [ ] User permission and role management
+- [ ] Data encryption and security scanning
+- [ ] GDPR and compliance feature setup
+- [ ] Audit logging and security monitoring
+- [ ] Automated security updates and patches
+
+## MCP Benefits
+
+### Developer Experience
+- **Zero Backend Configuration** - MCP handles all Supabase setup automatically
+- **Type-Safe APIs** - Auto-generated client SDKs with full type safety
+- **Real-time by Default** - Live data updates without manual subscription management
+- **Automatic Scaling** - Backend scales automatically based on usage
+- **Built-in Security** - RLS and authentication handled automatically
+
+### Production Ready
+- **High Availability** - Built-in redundancy and failover
+- **Global CDN** - Automatic content distribution and caching
+- **Monitoring & Alerts** - Comprehensive monitoring and alerting
+- **Automated Backups** - Point-in-time recovery and data protection
+- **Compliance Ready** - GDPR, SOC2, and other compliance features
+
+## Notes
+The Supabase MCP integration eliminates manual backend configuration and provides a fully automated, production-ready data layer that scales automatically and handles all the complex backend operations seamlessly.