Architecture

How the package is structured and how it interacts with your app.

Package structure

bmoni_embedded_wallets_cards/
├── constants/       EmbeddedWalletCacheKeys
├── contracts/       EmbeddedWalletReadDataSource
│                    EmbeddedWalletStorage
│                    EmbeddedWalletBalanceCache
├── failures/        EmbeddedFailure and subtypes
├── models/          EmbeddedWallet and all response/transaction types
├── notifiers/       EmbeddedWalletListNotifier
│                    EmbeddedWalletBalanceNotifier
│                    EmbeddedWalletTransactionsNotifier
└── widgets/         EmbeddedWalletCard
                     EmbeddedWalletTransactionsSection

---

Dependency direction

Your app (Riverpod providers, navigation, auth)
    │
    ▼  instantiates notifiers and provides contracts
Notifiers (EmbeddedWalletListNotifier, ...)
    │
    ▼  depend on contracts you implement
Contracts (EmbeddedWalletReadDataSource, EmbeddedWalletStorage, ...)
    │
    ▼  you implement these against your API / DB
Your data layer (HTTP client, local DB, in-memory cache, ...)

Widgets consume notifier state but never call contracts directly.

---

Data flow

1. Your Riverpod provider instantiates a notifier, injecting your contract implementations.
2. Your screen calls a notifier method (e.g. fetchWallets()).
3. The notifier calls the contract, maps the result to an Either<EmbeddedFailure, T>, and emits new state.
4. Widgets observe state and rebuild.

// 1. Provider — inject your contracts
final walletListProvider =
    StateNotifierProvider<EmbeddedWalletListNotifier, EmbeddedWalletListState>(
  (ref) => EmbeddedWalletListNotifier(
    walletDataSource: ref.watch(walletDataSourceProvider),
    storage: ref.watch(walletStorageProvider),
  ),
);

// 2. Screen — trigger a fetch
await ref.read(walletListProvider.notifier).fetchWallets();

// 3. Widget — observe state
final EmbeddedWalletListState state = ref.watch(walletListProvider);

---

Error model

All notifier methods return void / Future<void>. Failures are surfaced through the hasError / failure fields of each state class:

final state = ref.watch(walletListProvider);

if (state.hasError) {
  final EmbeddedFailure failure = state.failure!;
  // failure is one of the EmbeddedFailure subtypes
}

See Failures for all subtypes.

---

Offline & caching strategy

Each notifier accepts optional EmbeddedWalletStorage and EmbeddedWalletBalanceCache contracts. When a fetch fails (network error), the notifier transparently falls back to cached data:

// On first load, pass isCache: true to prefer cached data
await ref.read(walletBalancesProvider.notifier)
    .fetchWalletBalances(ids, isCache: true);

// On pull-to-refresh, bypass the cache
await ref.read(walletBalancesProvider.notifier)
    .fetchWalletBalances(ids, isCache: false);