architecture

Architecture Rules — flutter_core_modules

Layer Structure

This package uses strict Clean Architecture with three layers per feature:

domain/      ← pure Dart, no Flutter, no third-party imports
data/        ← implements domain abstractions, may use third-party SDKs
presentation/ ← Flutter + Riverpod only, no direct SDK calls

Dependency Direction (enforced)

• presentation → domain (ALLOWED)
• data → domain (ALLOWED)
• domain → nothing outside domain (ENFORCED — no Flutter, no third-party)
• presentation → data only to import Riverpod providers (ALLOWED)
• data → presentation (FORBIDDEN)
• domain → data (FORBIDDEN — only through abstract interfaces)

Either<L, R> — Error Handling

All operations that can fail return Future<Either<Failure, T>> or Either<Failure, T>.

// CORRECT — use Either for fallible operations
Future<Either<StorageFailure, String>> getDownloadUrl({...});

// WRONG — never throw exceptions across layer boundaries
Future<String> getDownloadUrl({...}) { throw Exception('...'); }

• L (Left) = Failure type (always a sealed class)
• R (Right) = success value
• Use .fold(onLeft, onRight) to consume Either values
• Never use try-catch in domain layer — only in data layer implementations

Failure Types

Define failures as sealed classes. One sealed class per feature domain:

// CORRECT
sealed class StorageFailure {}
class UnidentifiedStorageFailure extends StorageFailure {}
class EmptyCacheStorageFailure extends StorageFailure {}

// WRONG — never use String, int, or Exception as failure types

State Machine

All async data has exactly four states — use the core State<F, S> sealed class:

sealed class State<F, S> {}
class StartedState<F, S>       extends State<F, S> {} // initial
class LoadInProgressState<F, S> extends State<F, S> {} // loading
class LoadSuccessState<F, S>   extends State<F, S> {} // success
class LoadFailureState<F, S>   extends State<F, S> {} // failure