Flutter

lib/
  main.dart                 # bootstrap (shared)
  main_dev.dart             # flavored entrypoint -> runApp(const App(flavor: Flavor.dev))
  main_prod.dart
  app.dart                  # MaterialApp.router + ProviderScope wiring
  src/
    features/
      cart/
        presentation/       # widgets, screens, Riverpod consumers
        domain/             # entities, repository interfaces, Result/Failure (zero Flutter imports)
        data/               # DTOs, dio data sources, repository impls
    common/
      router/               # typed go_router + guards
      theme/                # ColorScheme.fromSeed, ThemeExtension tokens
      network/              # dio client + interceptors
      errors/               # Result, Failure sealed types
      widgets/              # shared reusable widgets

// BAD  — bang crashes in prod when user is null
final n = user!.name;

// GOOD — null-aware + fallback
final n = user?.name ?? 'Unknown';

// GOOD — if-case pattern promotes the binding
if (user case User(:final name)?) {
  greet(name);
}

// GOOD — switch expression over a nullable is exhaustive
final label = switch (user) {
  User(:final name) => name,
  null => 'Guest',
};

// BAD  — defers a null error to runtime
late String id;

// OK   — initialized in initState before any access
late final AnimationController _c;

// Runs both requests at once; .wait is the Dart 3 record concurrency extension.
final (user, count) = await (repo.user(), repo.count()).wait;

sealed class JobState {}
final class JobIdle extends JobState {}
final class JobRunning extends JobState { const JobRunning(this.pct); final double pct; }
final class JobDone extends JobState { const JobDone(this.url); final String url; }

Widget build(JobState s) => switch (s) {
  JobIdle() => const Text('Idle'),
  JobRunning(:final pct) => LinearProgressIndicator(value: pct),
  JobDone(:final url) => Link(url),
}; // compiler errors if a variant is unhandled

// In a State<T>:
await repo.save();
if (!context.mounted) return;
context.go('/done');

// Inside a Notifier (Riverpod 3):
await repo.save();
if (!ref.mounted) return;
ref.invalidate(listProvider);

// Fire-and-forget must be explicit, not a silently-dropped Future:
unawaited(analytics.log('checkout'));

// BAD — leaks a subscription on every rebuild
@override
Widget build(BuildContext context) { stream.listen(_onData); return const SizedBox(); }

extension type UserId(String value) {}
extension type OrderId(String value) {}

void loadUser(UserId id) { /* ... */ }
// loadUser('o_42');           // BAD — compile error: String is not a UserId
loadUser(const UserId('u_7')); // GOOD

final parsed = await Isolate.run(() => heavyParse(jsonBig));

// Sync Notifier — list mutation. (Function providers for async reads and
// AsyncNotifier guarded mutation -> references/architecture-and-state.md.)
@riverpod
class CartNotifier extends _$CartNotifier {
  @override
  List<CartItem> build() => const [];

  void add(CartItem item) => state = [...state, item];
  void remove(String id) => state = state.where((i) => i.id != id).toList();
}

final view = switch (ref.watch(productsProvider)) {
  AsyncData(:final value) => ProductList(value),
  AsyncError(:final error) => ErrorView(error),
  _ => const CircularProgressIndicator(),
};
final count = ref.watch(cartNotifierProvider.select((items) => items.length));

sealed class AuthState {}
final class AuthInitial extends AuthState {}
final class AuthLoading extends AuthState {}
final class AuthAuthed extends AuthState { const AuthAuthed(this.user); final User user; }
final class AuthFailed extends AuthState { const AuthFailed(this.message); final String message; }

class AuthCubit extends Cubit<AuthState> {
  AuthCubit(this._repo) : super(AuthInitial());
  final AuthRepository _repo;

  Future<void> login(String email, String password) async {
    emit(AuthLoading());
    final res = await _repo.login(email, password);
    emit(res.fold((u) => AuthAuthed(u), (f) => AuthFailed(f.message)));
  }
}

// UI:
BlocBuilder<AuthCubit, AuthState>(
  builder: (context, state) => switch (state) {
    AuthInitial() || AuthLoading() => const CircularProgressIndicator(),
    AuthAuthed(:final user) => HomeView(user),
    AuthFailed(:final message) => ErrorView(message),
  },
);

// BAD  — a Bloc that depends on another Bloc
CartBloc(this.authBloc);
// GOOD — share the repository, not the Bloc
CartBloc(this.cartRepo);

final theme = ThemeData(
  useMaterial3: true,
  colorScheme: ColorScheme.fromSeed(seedColor: const Color(0xFF6750A4), brightness: Brightness.light),
);
// BAD  color: Colors.blue
// GOOD color: Theme.of(context).colorScheme.primary

@TypedGoRoute<HomeRoute>(path: '/', routes: [TypedGoRoute<DetailRoute>(path: 'detail/:id')])
class HomeRoute extends GoRouteData with $HomeRoute {
  const HomeRoute();
  @override
  Widget build(BuildContext context, GoRouterState state) => const HomeScreen();
}

final router = GoRouter(
  routes: $appRoutes,
  refreshListenable: authListenable,
  redirect: (context, state) => authGuard(context, state),
);
const DetailRoute(id: '7').go(context); // typed navigation, no magic strings

final dio = Dio(BaseOptions(
  baseUrl: const String.fromEnvironment('API_URL'),
  connectTimeout: const Duration(seconds: 10),
  receiveTimeout: const Duration(seconds: 30),
));

dio.interceptors.add(InterceptorsWrapper(
  onRequest: (options, handler) async {
    final token = await secureStorage.read(key: 'auth_token');
    if (token != null) options.headers['Authorization'] = 'Bearer $token';
    handler.next(options);
  },
  onError: (error, handler) async {
    final isRetry = error.requestOptions.extra['_isRetry'] == true; // one-shot guard
    if (!isRetry && error.response?.statusCode == 401 && await refreshToken()) {
      error.requestOptions.extra['_isRetry'] = true;
      return handler.resolve(await dio.fetch(error.requestOptions));
    }
    handler.next(error);
  },
));

// GOOD — boundary returns a mapped Result; UI cannot crash on a wire error
Future<Result<Cart, Failure>> getCart();
// BAD  — leaks DioException into widgets
Future<Cart> getCart(); // throws DioException to the UI

// Unit — Riverpod 3 container helper.
final container = ProviderContainer.test();
final cart = container.read(cartNotifierProvider);

// Widget — override the controller with a fake.
await tester.pumpWidget(ProviderScope(
  overrides: [cartControllerProvider.overrideWith(FakeCartController.new)],
  child: const MaterialApp(home: CartScreen()),
));

// Golden — deterministic pixel comparison.
await expectLater(find.byType(CartCard), matchesGoldenFile('goldens/cart_card.png'));