core-architecture

Core Architecture — flutter_core_modules

This package is a shared Flutter library providing clean-architecture foundations consumed by multiple apps. It lives at lib/src/core/ and everything here is re-exported via lib/flutter_core_modules.dart.

---

1. Either — Functional Error Handling

File: lib/src/core/domain/utils/either.dart

A custom sealed class Either<L, R> (no external dependency) inspired by Scala/dartz:

sealed class Either<L, R> {
  T fold<T>(T Function(L) fa, T Function(R) fb);
}
class Right<L, R> extends Either<L, R> { R get value; }
class Left<L, R>  extends Either<L, R> { L get value; }

Convention: L is always the Failure type, R is the success value.

All use cases and repositories that can fail return Future<Either<Failure, Entity>>. Never throw exceptions across layer boundaries — wrap them in Left.

// Correct pattern in a use case:
Future<Either<StorageFailure, String>> call(...) =>
    _repository.getDownloadUrl(...);

// Consuming in a notifier:
final failureOrSuccess = await forwardedGet();
state = failureOrSuccess.fold(
  LoadFailureState.new,
  LoadSuccessState.new,
);

---

2. State — Sealed State Machine

File: lib/src/core/presentation/notifiers/state.dart

sealed class State<F, S> {}
class StartedState<F, S>      extends State<F, S> {}  // initial, no data
class LoadInProgressState<F, S> extends State<F, S> {} // loading, optional prev data
class LoadSuccessState<F, S>  extends State<F, S> { S get value; }
class LoadFailureState<F, S>  extends State<F, S> { F get value; }

• F = Failure type (e.g., StorageFailure)
• S = Success type (e.g., String, CustomerInfo)
• LoadInProgressState optionally carries previous f/s for "loading with previous data" UX patterns.

Pattern-matching in UI:

switch (state) {
  StartedState()                          => const SizedBox.shrink(),
  LoadInProgressState()                   => const CircularProgressIndicator(),
  LoadSuccessState(value: final url)      => Image.network(url),
  LoadFailureState()                      => ErrorIndicatorWidget(...),
}