Architecting Flutter Clean Apps

Markdown
---
name: architecting-flutter-clean-apps
description: Generates, audits, and enforces enterprise-grade Feature-First Clean Architecture for Flutter apps using Riverpod, GoRouter, fpdart/Either functional error handling, Supabase, Superwall, and PostHog. Use when building production Flutter apps, scaffolding new features, reviewing Flutter architecture, or when the prompt includes "go-setup" to trigger full boilerplate generation.
---

# Flutter Enterprise Clean Architecture

1. Domain: pure Dart only — no Flutter imports, no Supabase imports. Every fallible operation returns Future<Either<Failure, T>> or Stream<Either<Failure, T>>.
2. Data: catches all raw exceptions (PostgrestException, SocketException, etc.) at the repository implementation boundary and maps them to a Failure subtype. Models implement toEntity().
3. Presentation: controllers call UseCases, never repositories directly. ref.watch() drives UI; no business logic inside build().

Failures & UseCase Contract

DART
// lib/core/errors/failures.dart
import 'package:equatable/equatable.dart';

abstract class Failure extends Equatable {
  final String message;
  final int? statusCode;
  const Failure(this.message, [this.statusCode]);
  @override
  List<Object?> get props => [message, statusCode];
}

class ServerFailure extends Failure {
  const ServerFailure([super.message = 'A server error occurred. Please try again.', super.statusCode]);
}
class AuthFailure extends Failure {
  const AuthFailure([super.message = 'Authentication failed.', super.statusCode]);
}
class CacheFailure extends Failure {
  const CacheFailure([super.message = 'Unable to read or write local storage.']);
}
class NetworkFailure extends Failure {
  const NetworkFailure([super.message = 'No internet connection detected.']);
}

DART
// lib/core/utils/usecase.dart
import 'package:fpdart/fpdart.dart';
import '../errors/failures.dart';

abstract interface class UseCase<Type, Params> {
  Future<Either<Failure, Type>> call(Params params);
}
abstract interface class StreamUseCase<Type, Params> {
  Stream<Either<Failure, Type>> call(Params params);
}
class NoParams {
  const NoParams();
}

Theme Engine (M3 Seed + OLED Pitch-Black)

Use AppThemeGenerator.generate(primaryColor: seed, brightness: ..., oledPitchBlack: true). Default seed #4A6CF7. Buttons: 52px min height, 14px radius, zero elevation. Cards: surfaceContainer, 16px radius, hairline outline at 15% opacity.

Supabase Static Facade (AppBackend)

Expose as static methods, never instantiate: currentUser, isAuthenticated, authStateChanges, signInWithApple(), signInWithGoogle(), signInWithOtp(), signOut(), deleteAccount() (invokes delete-user-account edge function — required for Apple Guideline 5.1.1), streamCollection(), invokeFunction().

Growth Stack

• AnalyticsService wraps PostHog: identify(), track(), screen(). Fire track() on every onboarding step and monetization event.
• PaywallService wraps Superwall: init(), registerPlacement(placement, params, onFeatureUnlocked, onDismissed), restorePurchases().
• NotificationService wraps FCM + flutter_local_notifications, high-importance Android channel, foreground message → local notification bridge.

Reject standard slider-carousel onboarding. Always build a progressive micro-conversational funnel:

1. Pain-point selection (chip/button list) → auto-advance on tap
2. Quantified impact calculator (slider + derived stat, e.g. "hours lost/year")
3. Commitment screen → synthetic processing delay (~2.5–3s, "Building your tailored plan...") → paywall trigger before auth

Key rule: monetization precedes registration. Track every step transition via AnalyticsService.track('onboarding_step_completed', {'step': n}). See full OpalOnboardingScreen implementation for exact widget structure — replicate this pattern for any onboarding request rather than a PageView carousel.

Every generated app MUST include an Account screen with:

• Current identity display (email or "Anonymous Session")
• "Restore Purchases" → PaywallService.restorePurchases()
• Privacy Policy + Terms of Service links
• Delete Account with confirmation dialog warning of irreversibility → calls AppBackend.deleteAccount() → navigates to onboarding/login

Never ship a paywall-monetized app without this screen wired into routes.

• Always generate domain entities as immutable, Equatable-extending classes with no JSON/Supabase awareness.
• Repository implementations are the only place try/catch on raw SDK exceptions is allowed.
• Use @riverpod codegen annotations over manual StateNotifierProvider boilerplate.
• Default OLED pitch-black surfaces for dark mode unless the user specifies a different dark palette.
• Route guards (route_guards.dart) handle auth/onboarding redirects — never scatter if (!authenticated) checks inside screen widgets.
• Every monetization trigger point must fire a corresponding AnalyticsService.track() call.

• Don't let UseCase/domain code import package:flutter/material.dart or package:supabase_flutter.
• Don't call repositories directly from widgets or controllers — always go through a UseCase.
• Don't build multi-page PageView onboarding carousels — use the Opal conversational funnel pattern instead.
• Don't ship a paywall without a visible "Restore Purchases" and account deletion path (App Store rejection risk).
• Don't put business logic inside build() methods — compute state in controllers, watch results in the view.
• Don't skip mapping raw exceptions to Failure types — no unchecked exceptions may reach the presentation layer.