The Flutter client reads live. It has session storage but no record cache, connectivity monitor, durable write queue, conflict resolver, or background sync. The chat package also keeps messages in memory. An app that needs offline behavior must implement it explicitly.
Video tutorials for this topic
Storage boundaries
| Layer | SDK behavior | Application responsibility |
|---|---|---|
| Active session | Access/refresh tokens in secure storage; user in preferences | Configure platform support and isolate environments |
| Remembered sessions | Saved records, including token copies, in preferences | Use a secure custom SessionStore if retaining them |
| Business records | No persistent cache | Choose storage, encryption, expiry and account scope |
| Pending writes | No queue | Design persistence, idempotency and reconciliation per operation |
Partition caches by API origin, organization and identity. A cache key such as
leads alone can expose one organization's records after a switch. Stored data
also needs a timestamp so the UI can say when it was last fetched.
Fall back only for a network failure
Connectivity describes a network interface, not whether AppEngine is reachable. Make the request and handle its outcome. The following cache contract and helper can be used with an application-provided implementation; it deliberately does not prescribe a storage package:
import 'package:appmint_flutter_client/appmint_flutter_client.dart';
class CachedRows {
const CachedRows(this.rows, this.savedAt, {this.stale = false});
final List<Map<String, dynamic>> rows;
final DateTime savedAt;
final bool stale;
}
abstract class RowCache {
Future<CachedRows?> read(String scope);
Future<void> write(String scope, CachedRows value);
Future<void> clear(String scope);
}
Future<CachedRows> readWithCache({
required String scope,
required RowCache cache,
required Future<List<Map<String, dynamic>>> Function() fetch,
}) async {
final List<Map<String, dynamic>> rows;
try {
rows = await fetch();
} on AppmintNetworkException {
final old = await cache.read(scope);
if (old == null) rethrow;
return CachedRows(old.rows, old.savedAt, stale: true);
}
final fresh = CachedRows(rows, DateTime.now().toUtc());
await cache.write(scope, fresh);
return fresh;
}This example propagates cache read/write errors so the app can report a storage
failure separately. Decide whether a failed cache write should prevent showing
a successful fresh read. Never catch every exception and silently show old
data: 403, expired sessions, invalid queries and malformed responses need
different recovery. A cached private record is not proof of current permission.
Reconnection and lifecycle
Retry a failed read from a visible refresh action or after a network/resume
signal. Coalesce those triggers so they do not launch overlapping refreshes.
Cancel subscriptions in dispose, check mounted after awaited work, and
ignore responses from an earlier user or org after switching context. A request
timeout does not cancel work already accepted by the server.
Normal HTTP calls already retry recognized timeout and connection failures. See request retries before adding another retry loop. Multipart uploads and socket acknowledgments have different timeout and error behavior.
Writes with an unknown outcome
If a response is lost, the server may already have saved the action. The current
SDK retries ordinary writes on recognized transport failures, including
timeouts. For non-idempotent actions use transientRetries: 1, prevent duplicate
submissions while a call is pending, and read back the domain record after an
ambiguous failure. The separate 401 retry still applies.
A client-generated operation ID prevents duplication only when the server explicitly enforces it for that route. The generic repository has no documented universal idempotency-key contract. Its duplicate-create response is not a replacement for a durable operation ledger.
If a domain supports queueing, each entry needs the exact request payload, org, actor, creation time, dependency order and an operation identifier recognized by that server. Validate authorization again before replaying. Keep failed and conflicting entries visible; remove one only after confirmed acceptance. Do not replay a previous user's pending work under a new user's session.
What can be stale
A previously loaded catalog or schedule can remain useful with a timestamp. Live stock, payment state, ticket validity, queue position and access decisions need a fresh authoritative result before acting. A ticket scan must confirm admission with the server; a payment UI must not show “paid” because a request was queued. Provider delivery and card-reader acceptance require their own confirmation beyond a local saved row.
Sign-out and organization changes
auth.signOut() clears the SDK's active session. It leaves remembered accounts,
application preferences, cached business records, pending actions and chat
session IDs alone. Your application must clear or lock those scoped resources
and dispose account-bound controllers. Do the same for a forced sign-out from
auth.changes and for switchOrganization. Preserve unrelated hardware and
layout settings only when their ownership allows it.
See authentication, request errors, and the example apps for the live-request integrations this cache layer sits around.
