DEV Community: Mahmoud Alatrash

Your pm.max_children Math Is Wrong: Why Averages Kill Production Stability

Mahmoud Alatrash — Tue, 17 Mar 2026 23:45:46 +0000

Your pm.max_children Math Is Wrong: Why Averages Kill Production Stability

TL;DR: Don't set pm.max_children based on average worker memory — use P95 RSS instead. Measure it under peak traffic, apply a 1.2x safety factor, then cap workers by CPU (8–12/core for IO-bound, 2–4/core for CPU-bound). Set pm.max_requests to recycle workers, request_terminate_timeout to kill stuck ones, and monitor the FPM status page for saturation signals.

Most engineers configure pm.max_children by dividing available RAM by average worker memory. Simple division, clean number, ship it. But production traffic doesn't follow averages — a handful of heavy requests can push workers well past that number, and suddenly your "safe" config is swapping to disk or getting OOM-killed.

Instead of sizing for the average, size for what actually breaks things: P95 memory usage and how many workers your CPUs can realistically handle.

The Trap of Average-Based Sizing

Not all requests are equal. Most of your traffic is probably lightweight — simple API calls, quick reads. But then you've got the heavy hitters: data exports, complex reports, large serialization jobs. These are the ones that eat memory.

Say your numbers look like this:

Average worker memory: 50 MB
P95 worker memory: 120 MB
Server RAM: 8 GB

With average-based math, you'd set pm.max_children to 160. On a normal day, that works — only a few workers spike to 120 MB at any given time. The problem starts when traffic shifts. A marketing campaign goes out, a retry storm kicks in, or someone triggers a batch job. Suddenly it's not 5% of your workers running heavy — it's way more.

Half the pool at peak usage: 80 workers × 120 MB = 9.6 GB — you just blew past your 8 GB.

You won't even make it to the RAM ceiling cleanly. The kernel starts struggling with page cache and buffers, swap kicks in, everything slows to a crawl, and then the OOM killer shows up and takes out processes.

Bottom line: don't size for a good day. Size for when traffic turns against you.

Measuring the Right Metrics: RSS, PSS, and VSZ

Before you start measuring, you need to know what to measure. There are three memory metrics you'll run into, and they don't all tell you the same thing.

VSZ (Virtual Size): The total virtual address space the process has mapped. This includes shared libraries, reserved-but-unused memory, and all sorts of stuff that never touches physical RAM. Ignore it for sizing purposes.
RSS (Resident Set Size): The actual physical memory a worker is using right now. This is what most people use for capacity planning — and it works, with one catch. PHP-FPM workers are forked from a master process, so they share a bunch of memory pages (libc, the PHP binary, loaded extensions) through copy-on-write. RSS counts those shared pages in every worker.

That means if you add up RSS across all your workers, you'll get a number that's higher than reality.

PSS (Proportional Set Size): Splits shared pages proportionally across the processes using them. More accurate than RSS, but harder to collect — you have to read /proc/<pid>/smaps.

Which one should you use? Go with RSS. Yes, it overcounts a bit, but that means your sizing ends up conservative — you'll have slightly more headroom than the math suggests. If you're in a tight container environment where every MB counts, use PSS instead.

How to Measure P95 RSS

Don't rely on a single snapshot. Run ps against your worker pool repeatedly during peak hours — every minute, over a few days — and pull the 95th percentile from the collected data.

Here's a one-liner to check what your pool looks like right now:

# Get RSS of worker processes only (exclude master)
ps --no-headers -o rss --ppid $(pgrep -f 'php-fpm: master') | sort -n | awk '{a[NR]=$1} END {print "P95 RSS: " int(a[int(NR*0.95)]/1024) " MB"}'

To collect data over time, throw it on a cron and log the results:

# Add to crontab — runs every minute, workers only
* * * * * ps --no-headers -o rss --ppid $(pgrep -f 'php-fpm: master') >> /var/log/php-fpm-rss.log

More samples across real traffic = a number you can actually trust.

So what does "P95" actually mean here? You take all the worker RSS values you've collected during peak hours, sort them, and find the point where 95% fall below. That's your answer: "95% of the time, a worker uses less than X MB." Use that X for your sizing math.

Memory Growth and Worker Lifecycle

PHP workers don't stay the same size forever. The longer a worker lives, the more memory it tends to accumulate — fragmentation, extension allocations, internal caches, allocator behavior. It adds up.

That's what pm.max_requests is for. Set it to something like 800 or 1000, and workers get killed and respawned after that many requests. It keeps memory usage from drifting upward over time.

A note on OPcache: OPcache helps by caching compiled bytecode in shared memory, so workers don't re-compile the same files. But it doesn't replace per-worker RAM — each worker still needs its own memory for the actual request execution.

PHP-FPM Process Modes

PHP-FPM gives you three process management modes. Each one handles worker lifecycle differently:

Mode	Behavior	Best For	Trade-off
`static`	All workers are forked at startup and stay alive. Pool size is always `pm.max_children`.	High-traffic apps with predictable load. No fork latency at all.	You pay the full memory cost upfront, even if traffic is low.
`dynamic`	Keeps a pool of idle workers between `min_spare` and `max_spare`, spinning up more as needed up to `max_children`.	Most production workloads. Good balance of responsiveness and resource use.	Some latency when scaling up. You need to tune the spare values.
`ondemand`	Zero workers when idle. A new worker is forked for each request and killed after `pm.process_idle_timeout`.	Low-traffic sites, dev environments, shared hosting — anywhere memory matters more than speed.	Fork overhead on every request. Don't use this if latency matters.

For production with real traffic, static is the most predictable; dynamic is the safe default. Only use ondemand if saving memory is more important than response time.

Realistic Capacity Planning: A Practical Example

Server Specs: 16 GB RAM / 4 CPU Cores

1. Reserve System Memory

Not all 16 GB is yours. The OS, Nginx, and whatever else is running on the box need their share. Here's a rough breakdown:

Component	Estimated Usage
Linux kernel / page cache / buffers	~1.5 GB
Nginx	~200–500 MB
Monitoring agents (node_exporter, log shipper, etc.)	~200–500 MB
Safety buffer	~500 MB

That's about 2.5–3 GB gone before PHP-FPM even starts. We'll use 3 GB to be safe.

16 GB Total - 3 GB Reserved = 13 GB for PHP-FPM

If you're running Redis, MySQL, or anything else on the same host, subtract those too.

2. Calculate the Theoretical Limit (RAM)

Let's say your measured P95 RSS is 150 MB per worker. Multiply that by 1.2 as a safety margin, then divide:

13,000 MB / (150 MB × 1.2) = 72 workers

Why multiply by 1.2? Because P95 isn't the ceiling — workers keep growing between recycles, the kernel eats more memory the more processes you run (page tables, file descriptors, socket buffers), and sometimes you'll hit above P95. The 1.2x gives you breathing room. If your app loads big datasets or your workers bloat aggressively, bump it to 1.3–1.5.

3. Determine the Practical Limit (CPU)

RAM says 72 workers. But 4 cores can't actually run 72 workers at the same time — it depends on what those workers are doing.

IO-bound workloads (most web apps): Workers spend most of their time waiting — on the database, an external API, disk reads. While they wait, they're not using CPU. So you can run more workers than you have cores, because most of them are idle at any given moment. Start with 8–12 workers per core.

CPU-bound workloads (image processing, PDF generation, heavy math): Workers are actively burning CPU for most of the request. Go past your core count and you're just adding context-switch overhead for no gain. Start with 2–4 workers per core.

Not sure which one you are? Open top or htop during peak traffic. If CPU per core stays under 50–60% while workers are all busy, you're IO-bound. If cores are pinned at 90%+ with fewer workers, you're CPU-bound.

For our 4-core box with a typical web workload (mostly IO-bound, some heavier endpoints):

4 cores × 8–10 workers/core = 32–40 workers

That's well under the 72 workers RAM would allow — and that's normal. CPU is almost always the tighter limit, not memory.

4. Check Downstream Constraints

Your workers don't run in isolation — each one can open a database connection. If you've got 40 workers but your database only allows 20 concurrent connections, half your workers will sit there waiting during peak load. Before you finalize your pm.max_children, make sure your database, cache, and any external services can actually handle that many concurrent connections.

Throughput Estimation

Your worker count sets the ceiling on how many requests you can handle per second:

Max Throughput ≈ Active Workers / Average Request Duration

This is a best-case number — it assumes every worker is busy and nothing is stuck in a queue. In reality, throughput is lower. Under light traffic, you're just serving what comes in. Under heavy traffic, requests start queueing and latency climbs in ways this formula doesn't show. Think of it as a ceiling, not a prediction.

Quick PHP-FPM Configuration Example

Here's what a reasonable config looks like for a mid-sized server (4 vCPUs, 16 GB RAM) running mixed traffic with pm = dynamic. These values go in your pool config file — usually /etc/php/8.x/fpm/pool.d/www.conf. After any change, reload with systemctl reload php8.x-fpm.

pm = dynamic
pm.max_children = 35
pm.start_servers = 8
pm.min_spare_servers = 5
pm.max_spare_servers = 10
pm.max_requests = 800

request_terminate_timeout = 30s
request_slowlog_timeout = 5s
slowlog = /var/log/php-fpm/slow.log

Why these values?

max_children (35): Fits the 8–10 workers/core range for a 4-core machine. Keeps you under P95 RAM limits and won't exhaust your database connections.
start/spare servers: Enough idle workers ready to absorb small traffic spikes without the delay of forking new ones.
max_requests (800): Workers recycle often enough to prevent memory bloat, but not so often that you're constantly forking.
request_terminate_timeout (30s): If a worker has been running for 30 seconds, something is wrong — kill it. Without this, one stuck request (infinite loop, deadlocked API call) holds a worker forever and your pool slowly shrinks.
request_slowlog_timeout (5s) / slowlog: Any request over 5 seconds gets its stack trace logged. This is how you find the slow endpoints that are eating your pool alive.

Observability

Enabling the FPM Status Page

The status page isn't on by default. Add this to your pool config:

pm.status_path = /fpm-status

Then expose it through Nginx — lock it down to localhost or your internal network:

location /fpm-status {
    allow 127.0.0.1;
    deny all;
    fastcgi_pass unix:/run/php/php-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;
}

Key Metrics to Monitor

Active Processes: How many workers are busy right now.
Max Children Reached: This fires when your app needs more workers but has hit the ceiling. You're saturated.
Listen Queue: Requests waiting in line because every worker is busy. If this number stays above zero, users are waiting.

Alert Thresholds

max_children_reached keeps incrementing — you're hitting your pool ceiling regularly. Either you need more workers, or slow endpoints are hogging them for too long.
listen_queue > 0 for more than 10–15 seconds — requests are actively queueing. Latency is climbing, and if it doesn't clear up, 502s and 504s are next.
Worker RSS above your P95 baseline — something is leaking memory or processing an unexpectedly heavy payload. Make sure pm.max_requests is set, and check the slow log to find the culprit.

Metrics Pipeline

If you're using Prometheus and Grafana, php-fpm_exporter scrapes the FPM status page and exposes everything as Prometheus metrics. Hook it up and you can dashboard and alert on all the signals above.

Conclusion

Sizing PHP-FPM on averages is a bet that works until it doesn't.

Size for the worst case. Use P95 RSS, not averages. Sample it repeatedly under real peak traffic.
Respect your CPU. RAM might allow 70 workers, but your cores probably can't. Use workers-per-core ratios and check your database can handle the concurrency.
Keep workers healthy. pm.max_requests prevents memory bloat. request_terminate_timeout prevents stuck workers from eating your pool.
Watch the right signals. Enable the FPM status page, track active processes and listen queue, and alert before users start complaining.
Know when to stop tuning. There's only so much you can squeeze out of one server. When you hit that wall, scale horizontally behind a load balancer or push heavy work (exports, PDFs, reports) to background queues.
Test it for real. Formulas give you a starting point. Load test with k6, wrk, or Locust in a staging environment to see where things actually break.
Running containers? Same math applies, but the stakes are higher — an OOM-kill takes out the entire container, not one worker. Size your memory limits around pm.max_children × P95 RSS × safety factor, not the other way around.

Deep-Dive: Building a Production-Ready Navigation Observability System in Flutter

Mahmoud Alatrash — Wed, 18 Feb 2026 20:48:57 +0000

The Black Box Problem

Navigation is the backbone of every mobile app. Yet, in most production environments, it's completely invisible. Most teams instrument API calls and screen views, but the actual user journey between screens is treated as a black box.

This is a catastrophic mistake at scale.

When navigation breaks, you're debugging blind. When product asks for user flows, you're guessing. When QA finds an edge case, you can't reproduce it.

I built a production-grade navigation observability system to fix this. Not a logging hack. A real architectural solution with zero performance impact, strict privacy by default, and Clean Architecture.

This article breaks down exactly how I built it, and why certain architectural trade-offs matter more than textbook rules.

Let's dive in.

The Three Pillars: Why Most Solutions Crumble

Building observability isn't just about dumping data into logs. After evaluating third-party tools and building prototypes, I realized that real production observability must stand on three non-negotiable pillars:

1. Zero-Overhead Performance

Users navigate constantly (50-100 times per session). If your observability adds even 5ms per route, you are degrading the UX and burning battery at scale.

My hard limit was < 0.5ms per navigation. Not "acceptable" overhead—invisible overhead. I achieved this not through brute-force optimization, but through architectural design: zero-copy paths and early returns.

2. Privacy by Default (Not by Convention)

Route arguments carry highly sensitive data: tokens, user IDs, payment details. One logging accident, and you're facing a GDPR nightmare.

Most solutions rely on developers "remembering" to enable sanitization. Humans forget. The architecture shouldn't.
My approach: Strict by Default. In production, 14 sensitive patterns are automatically redacted. The system doesn't trust the developer's memory; it relies on paranoid code.

3. Architecture That Welcomes Change

Clean Architecture often gets called "over-engineered"—until you need to swap your routing package, or test a deeply coupled analytics logger.

Clean Architecture isn't about being fancy; it's about being free. Free to test, change, and extend.
The implementation uses 4 distinct layers. The domain layer has zero Flutter dependencies. Want to switch from auto_route to go_router? Just write a new adapter. Need to add Firebase Analytics? Add a new listener. Zero breaking changes.

The Architecture: Four Layers, Zero Shortcuts

We built the system as four distinct layers. No monolithic classes. No "God objects." Just clean separation of concerns:

Domain Layer (Business Logic)
    ↓ defines interfaces
Data Layer (Event Bus Implementation)
    ↓ provides infrastructure
Infrastructure Layer (Adapters & Listeners)
    ↓ consumes events
DI Layer (Lifecycle Management)

Each layer has one job. Each layer is independently testable. Each layer can be mocked, swapped, or extended without touching the others.

This is what Clean Architecture looks like when you actually build it, not just talk about it.

The Domain Layer: Contracts Over Concrete

Now that you understand why we built this, let me show you how. We start at the core—the domain layer where everything begins.

The beauty of starting with pure business logic is that you're forced to think clearly. No framework noise. No implementation details. Just: "What is a navigation event, really?"

NavigationEvent: The Core Entity

At the heart of the system is an immutable event entity that captures everything we need:

class NavigationEvent {
  final NavigationEventType type;      // push, pop, replace, tabChange
  final RouteInfo? from;                // Source route (null for app launch)
  final RouteInfo to;                   // Destination route
  final Map<String, dynamic>? arguments; // Sanitized route arguments
  final DateTime timestamp;             // For ordering and timing analysis
  final String? sessionId;              // Reserved for future session tracking
}

The entity is deliberately dumb—no logic, just data. This makes it trivial to serialize, test, and reason about.

RouteInfo: Platform-Agnostic Abstraction

The RouteInfo class wraps route metadata in a way that's completely decoupled from Flutter's Route class:

class RouteInfo {
  final String name;                    // Route name (e.g., 'ProfileRoute')
  final String path;                    // Full path (e.g., '/profile')
  final Map<String, String>? parameters; // Reserved for query params
  final String? title;                  // Reserved for screen titles

  const RouteInfo({
    required this.name,
    required this.path,
    this.parameters,
    this.title,
  });
}

No Flutter imports. No framework coupling. Pure Dart. This abstraction lets us swap routing libraries without touching the domain layer—exactly what platform independence means in practice.

INavigationEventBus: Publish-Subscribe Contract

We needed a way to broadcast navigation events to multiple consumers without tight coupling. The interface is deliberately simple:

abstract class INavigationEventBus {
  void publish(NavigationEvent event);
  Stream<NavigationEvent> subscribe();
  bool get hasActiveListeners;
  Future<void> dispose();
}

Notice what's missing: no buffering, no replay, no persistence. Navigation events are ephemeral—if a listener subscribes late, it doesn't receive historical events. This keeps the system simple and prevents memory leaks from unbounded event queues.

INavigationListener: Consumer Contract

Listeners follow a standard lifecycle:

abstract class INavigationListener {
  String get name;
  void startListening(INavigationEventBus eventBus);
  Future<void> stopListening();
  bool get isListening;
}

This contract enforces explicit lifecycle management. Listeners must be started, and they must be stopped. No implicit subscriptions that leak.

The Data Layer: That "Crazy" Race Condition Decision

The event bus implementation uses Dart's StreamController.broadcast():

class NavigationEventBusImpl implements INavigationEventBus {
  late final StreamController<NavigationEvent> _controller;

  NavigationEventBusImpl() {
    _controller = StreamController<NavigationEvent>.broadcast();
  }

  void publish(NavigationEvent event) {
    if (_controller.isClosed) return;

    try {
      _controller.add(event);
    } catch (e, stack) {
      log('Error publishing: $e');
    }
  }
}

The Race Condition Everyone Notices

If you're an experienced engineer reading this, your instincts are probably screaming right now. The code checks isClosed, then calls add(). What if dispose() gets called in that exact microsecond in between? It throws a StateError.

"You need a Mutex!" "Add a Lock!" "This will crash in production!"

And you are... technically correct. There IS a race condition. But here's what makes this interesting:

That race only happens during app shutdown. And when it does, the try-catch handles it gracefully. The app is already closing. The user doesn't care. The event was never going to be processed anyway.

Now, here's the real trade-off: adding a Mutex or Lock would fix the race. It would also add ~0.01-0.1ms overhead to every single navigation event. Every single one.

Think about what that means. It means guarding against an edge case that:

Only occurs at app shutdown
Is already handled by the try-catch block
Has absolutely zero user impact

By imposing overhead on:

Every navigation
Every user
Every session
Forever

The architectural decision: I chose to keep the "bug." I documented it thoroughly in the codebase and explained the trade-off.

This is what pragmatic engineering looks like. Not textbook perfect. Production perfect.

The Entry Point: The AutoRoute Adapter

Here's the architectural reality: auto_route is a third-party routing library. Today it's auto_route. Tomorrow it could be go_router or some custom solution. If I let auto_route's types leak into my domain layer—into NavigationEvent, into INavigationEventBus—I'm locked in. Swapping routing libraries means rewriting the entire observability system.

Unacceptable.

The Adapter Pattern solves this. I build a thin infrastructure layer that extends AutoRouteObserver, listens for route changes, translates them into my platform-agnostic domain events, and publishes them to the event bus. The domain layer never sees Route. It never sees AutoRouteObserver. It only sees NavigationEvent and RouteInfo.

The Implementation

class AutoRouteObserverAdapter extends AutoRouteObserver {
  final INavigationEventBus _eventBus;
  final ArgumentSanitizationConfig _sanitizationConfig;

  AutoRouteObserverAdapter(
    this._eventBus, [
    ArgumentSanitizationConfig? sanitizationConfig,
  ]) : _sanitizationConfig = sanitizationConfig ?? ArgumentSanitizationConfig.strict;

  @override
  void didPush(Route route, Route? previousRoute) {
    _publishEvent(
      type: NavigationEventType.push,
      route: route,
      previousRoute: previousRoute,
    );
  }

  @override
  void didPop(Route route, Route? previousRoute) {
    _publishEvent(
      type: NavigationEventType.pop,
      route: route,
      previousRoute: previousRoute,
    );
  }

  @override
  void didReplace({Route? newRoute, Route? oldRoute}) {
    if (newRoute == null) return;
    _publishEvent(
      type: NavigationEventType.replace,
      route: newRoute,
      previousRoute: oldRoute,
    );
  }

  @override
  void didInitTabRoute(TabPageRoute route, TabPageRoute? previousRoute) {
    _publishEvent(
      type: NavigationEventType.tabChange,
      route: route as Route,
      previousRoute: previousRoute as Route?,
    );
  }

  @override
  void didRemove(Route route, Route? previousRoute) {
    _publishEvent(
      type: NavigationEventType.pop,
      route: route,
      previousRoute: previousRoute,
    );
  }

  void _publishEvent({
    required NavigationEventType type,
    required Route route,
    Route? previousRoute,
  }) {
    if (!_eventBus.hasActiveListeners) return;

    try {
      final event = NavigationEvent(
        type: type,
        from: previousRoute != null ? _extractRouteInfo(previousRoute) : null,
        to: _extractRouteInfo(route),
        arguments: _extractArguments(route),
        timestamp: DateTime.now(),
      );

      _eventBus.publish(event);
    } catch (e, stack) {
      log('Error creating navigation event: $e', name: 'AutoRouteObserverAdapter', error: e, stackTrace: stack);
    }
  }

  RouteInfo _extractRouteInfo(Route route) {
    final rawName = route.settings.name;
    if (rawName == null || rawName.isEmpty) {
      return const RouteInfo(name: 'UnknownRoute', path: '/unknown');
    }

    final startsWithSlash = rawName.startsWith('/');
    final name = startsWithSlash ? rawName.substring(1) : rawName;
    final path = startsWithSlash ? rawName : '/$rawName';

    return RouteInfo(name: name, path: path);
  }

  Map<String, dynamic>? _extractArguments(Route route) {
    try {
      final args = route.settings.arguments;
      if (args == null) return null;

      if (args is Map<String, dynamic>) {
        return _sanitizeArguments(args);
      }

      if (args is Map) {
        final converted = <String, dynamic>{};
        args.forEach((key, value) {
          if (key is String) {
            converted[key] = value;
          }
        });
        return _sanitizeArguments(converted);
      }

      return {'value': args.toString()};
    } catch (e, stack) {
      log('Error extracting route arguments: $e', name: 'AutoRouteObserverAdapter', error: e, stackTrace: stack);
      return null;
    }
  }

  Map<String, dynamic> _sanitizeArguments(Map<String, dynamic> args) {
    if (!_sanitizationConfig.enabled) return args;

    // Performance: Zero-copy fast-path if no sensitive keys (80%+ of cases)
    if (!args.keys.any(_sanitizationConfig.isSensitiveKey)) return args;

    // Only allocate when needed
    return args.map((key, value) => MapEntry(
      key,
      _sanitizationConfig.isSensitiveKey(key) ? _sanitizationConfig.placeholder : value,
    ));
  }
}

What This Achieves

The adapter is the only place in the codebase that imports auto_route. It's the only place that knows about Flutter's Route class. Everything downstream—the event bus, the listeners, the domain entities—operates on pure Dart abstractions.

Notice the critical optimization: if (!_eventBus.hasActiveListeners) return;. If no listeners are registered, the adapter does zero work. No route info extraction. No argument sanitization. No event creation. This keeps the hot path lean when observability is disabled.

The _extractRouteInfo method handles the string manipulation (stripping leading slashes) and caches the startsWith('/') result to avoid duplicate checks. The _sanitizeArguments method implements the zero-copy fast path—checking for sensitive keys before allocating a new map.

Integration

The adapter gets registered in the DI container:

final sanitizationConfig = kDebugMode
    ? ArgumentSanitizationConfig.disabled
    : ArgumentSanitizationConfig.strict;

it.registerLazySingleton<AutoRouteObserverAdapter>(
  () => AutoRouteObserverAdapter(
    it<INavigationEventBus>(),
    sanitizationConfig,
  ),
);

And injected into the router:

MaterialApp.router(
  routerDelegate: _appRouter.delegate(
    navigatorObservers: () => [
      inject.sl<AutoRouteObserverAdapter>(),
    ],
  ),
  routeInformationParser: _appRouter.defaultRouteParser(),
)

That's the entire surface area. One adapter. One injection point. If I swap to go_router tomorrow, I write a new adapter that implements their observer interface. The domain layer never changes. The event bus never changes. The listeners never change.

This is what architectural boundaries actually look like in production code.

The Infrastructure Layer: The Zero-Copy Breakthrough

When We Discovered the 80/20 Rule

Early profiling showed argument sanitization eating 60% of the overhead. Not good. It needed to be faster.

This led me to a critical architectural question: "How often do routes actually carry sensitive arguments?"

After analyzing the real-world navigation patterns, the answer was clear: Less than 20% of the time.

Most navigation is simple: Home → Profile → Settings. No tokens. No passwords. No credit cards. Just route names.

This realization triggered the main breakthrough: the zero-copy fast path.

The Code That Changed Everything

Map<String, dynamic> _sanitizeArguments(Map<String, dynamic> args) {
  if (!_sanitizationConfig.enabled) return args;

  // The magic: check BEFORE allocating
  if (!args.keys.any(_sanitizationConfig.isSensitiveKey)) return args;

  // Only pay the cost when we actually need to
  return args.map((key, value) => MapEntry(
    key,
    _sanitizationConfig.isSensitiveKey(key) 
      ? _sanitizationConfig.placeholder 
      : value,
  ));
}

Look at that second line. if (!args.keys.any(_sanitizationConfig.isSensitiveKey)) return args;

That single line checks if ANY key is sensitive. If not—and this is 80%+ of the time—we return the original map. No allocation. No copy. No iteration. Just return.

Zero. Copy.

When we DO find sensitive keys, we use args.map() to create a new map with redacted values. The functional style is clean, and the Dart VM loves it.

But here's what's beautiful: we only pay that cost when we actually need to. Four out of five times, we just... don't.

O(1) Pattern Matching

The isSensitiveKey() check could be a performance bottleneck if implemented naively. We pre-compute a Set<String> of lowercase patterns at construction:

class ArgumentSanitizationConfig {
  late final Set<String> _sensitiveKeysLowerSet;

  ArgumentSanitizationConfig({
    required this.enabled,
    required this.sensitiveKeys,
  }) {
    _sensitiveKeysLowerSet = sensitiveKeys.map((k) => k.toLowerCase()).toSet();
  }

  bool isSensitiveKey(String key) {
    if (!enabled) return false;
    final keyLower = key.toLowerCase();
    return _sensitiveKeysLowerSet.any((pattern) => keyLower.contains(pattern));
  }
}

The late final keyword is crucial here—it defers initialization until first access but guarantees immutability after that. The Set provides O(1) average-case lookups, dramatically faster than iterating a list of patterns.

Behavior-Based Configuration

We deliberately chose behavior-based naming over environment-based:

static final strict = ArgumentSanitizationConfig(
  enabled: true,
  sensitiveKeys: defaultSensitiveKeys,
);

static final disabled = ArgumentSanitizationConfig(
  enabled: false,
  sensitiveKeys: [],
);

Not .production() and .development(), but .strict and .disabled. Why? Environment-based names don't scale. When you have dev, staging, QA, pre-prod, and prod environments, "production" becomes ambiguous. Behavior-based names describe what the config does, not where it runs.

This is a subtle but important architectural decision that future-proofs the design.

The DI Layer: Lifecycle Management

GetIt registration with disposal callbacks is the secret sauce that prevents memory leaks:

class NavigationServiceProvider implements ServiceProvider {
  Future<void> register(GetIt it) async {    
    // Event bus with disposal
    it.registerLazySingleton<INavigationEventBus>(
      () => NavigationEventBusImpl(),
      dispose: (bus) => bus.dispose(),
    );

    final eventBus = it<INavigationEventBus>();

    // Listener with disposal
    final loggingListener = LoggingNavigationListener();
    loggingListener.startListening(eventBus);
    it.registerSingleton<LoggingNavigationListener>(
      loggingListener,
      dispose: (listener) => listener.stopListening(),
    );
  }
}

When the app shuts down (or when we reset GetIt in integration tests), these disposal callbacks execute automatically. The StreamController closes, the StreamSubscriptions cancel, and we leak nothing.

This is production-grade lifecycle management. It works in hot reload, in integration tests, and in production.

Silent Production Logging: The Consumer

Because of the Clean Architecture, consuming navigation events is trivial. The listener has zero coupling to auto_route, zero coupling to Flutter's Route class. It just subscribes to the stream and reacts.

The Implementation

class LoggingNavigationListener implements INavigationListener {
  StreamSubscription<NavigationEvent>? _subscription;

  @override
  String get name => 'LoggingNavigationListener';

  @override
  void startListening(INavigationEventBus eventBus) {
    if (_subscription != null) {
      log('Warning: $name already listening', name: 'Navigation');
      return;
    }

    _subscription = eventBus.subscribe().listen(
      _onNavigationEvent,
      onError: _onError,
      cancelOnError: false, // Continue listening even if errors occur
    );

    log('$name started', name: 'Navigation');
  }

  void _onNavigationEvent(NavigationEvent event) {
    // Silent in production - single boolean check (~0.001ms overhead)
    if (!kDebugMode) return;

    try {
      // Basic navigation log
      final fromRoute = event.from?.name ?? 'App Start';
      log('Navigation: $fromRoute → ${event.to.name} (${event.type.value})', name: 'Navigation');

      // Additional details (paths, arguments, timestamp)
      _logDebugDetails(event);
    } catch (e, stack) {
      // Errors in logging never affect navigation
      log('Error in $name while logging event: $e', name: 'Navigation', error: e, stackTrace: stack);
    }
  }

  void _logDebugDetails(NavigationEvent event) {
    if (event.from != null) {
      log('  From: ${event.from!.path}', name: 'Navigation', level: 500);
    }
    log('  To: ${event.to.path}', name: 'Navigation', level: 500);

    if (event.arguments != null && event.arguments!.isNotEmpty) {
      log('  Arguments: ${event.arguments}', name: 'Navigation', level: 500);
    }

    log('  Timestamp: ${event.timestamp.toIso8601String()}', name: 'Navigation', level: 500);

    // This is where Firebase Analytics, Datadog, or Mixpanel would go
    // analytics.logEvent('navigation', {...});
  }

  void _onError(Object error, StackTrace stack) {
    log('Error in $name event stream: $error', name: 'Navigation', error: error, stackTrace: stack);
  }

  @override
  Future<void> stopListening() async {
    await _subscription?.cancel();
    _subscription = null;
  }

  @override
  bool get isListening => _subscription != null;
}

The kDebugMode Optimization

Notice the early return: if (!kDebugMode) return;. In production builds, this is a single boolean check. No string formatting. No I/O. No allocations. Overhead: ~0.001ms.

In debug builds, the listener provides full structured logging with route paths, arguments, and timestamps. Exactly what developers need during development. Exactly zero overhead in production.

The Open-Closed Win

The listener knows nothing about auto_route. Nothing about adapters. It just consumes NavigationEvent objects from a stream.

Want to add Firebase Analytics? Implement INavigationListener. Want to track in Datadog? Implement INavigationListener. Want to store locally for crash reporting? Implement INavigationListener.

class FirebaseNavigationListener implements INavigationListener {
  final FirebaseAnalytics _analytics;

  @override
  void startListening(INavigationEventBus eventBus) {
    _subscription = eventBus.subscribe().listen((event) {
      _analytics.logEvent(
        'navigation',
        parameters: {
          'from': event.from?.name,
          'to': event.to.name,
          'type': event.type.value,
        },
      );
    });
  }

  // ...rest of interface implementation
}

Add listeners without touching the router, the adapter, or the event bus. Open for extension, closed for modification. This is what the Open-Closed Principle actually looks like in production code.

Performance Analysis

Let's break down the overhead per navigation event:

Operation	Cost	Frequency
`hasActiveListeners` check	~0.001ms	Every navigation
Route info extraction	~0.1ms	Every navigation
Argument sanitization (fast-path)	~0.001ms	80% of navigations
Argument sanitization (copy)	~0.2ms	20% of navigations
Event creation	~0.05ms	Every navigation
Stream publish	~0.05ms	Every navigation
Total (typical)	~0.3ms	Per navigation

For context, a typical route transition animation takes 300ms. Our observability overhead is 0.1% of the transition time. Imperceptible to users, negligible in profiling.

The Testing Win: Pure Unit Tests

There's one final architectural benefit that can't be ignored: testing.

Testing navigation in Flutter usually means writing slow, flaky WidgetTests that depend on the actual Router. But because the domain layer has zero Flutter dependencies, testing a listener requires zero UI code. You just inject a fake event bus:

test('Analytics listener logs navigation events', () {
  final fakeEventBus = FakeNavigationEventBus();
  final listener = AnalyticsNavigationListener(mockAnalytics);

  listener.startListening(fakeEventBus);
  fakeEventBus.publish(NavigationEvent.test());

  verify(() => mockAnalytics.logEvent('navigation', any())).called(1);
});

No real navigator. No real routes. Pure, lightning-fast unit tests.

5 Hard Truths from Production

Observability is Day-1 Infrastructure: Stop treating navigation tracking as a late-stage retrofit. If you can't see the flow, you're debugging blind.
Profile First, Optimize What Hurts: Guessing performance is for amateurs. Profiling proved sanitization was my 60% bottleneck, preventing useless micro-optimizations elsewhere.
Idiomatic Dart is Fast Dart: Don't outsmart the VM. High-order functions like .any() and .map() are not just cleaner; they are heavily optimized.
Document the "Why" in the Code: The race condition trade-off is documented right where it happens. Wikis drift; code doesn't.
Name by Behavior, Not Environment: Using ArgumentSanitizationConfig.strict instead of .production decoupled the logic from the environment and saved future refactoring.

Conclusion: Architecture as Liberation

The real win isn't the code. The win is what the code enables. Product gains visibility into user journeys. Engineering reproduces bugs with exact event sequences. QA has systematic coverage instead of blind spots. Support understands user context during troubleshooting.

This is foundational infrastructure. It's the difference between flying blind and making data-driven decisions. Between a three-day debugging marathon and a five-minute root-cause analysis.

Architecture isn't about being fancy. It's about being free. Free to test. Free to change. Free to extend. That's what Clean Architecture provides. That's what pragmatic trade-offs preserve. That's what profiling-first optimization delivers.

Code Repository

The complete implementation is available in the project repository under lib/core/navigation/:

11 files. Zero third-party dependencies beyond auto_route and GetIt.

Full Source Code:

🐙 Flutter Production Architecture on GitHub

If this series helped you:

⭐ Star the GitHub repository
💬 Share your implementation experiences in the comments
🔗 Share with your team.

Questions or improvements? Open an issue or PR on the GitHub repo. This is a living architecture—feedback makes it better.

From 0.3% Crash Rate to Zero: Scaling Flutter Cache with Batching, Locking, and Observable State

Mahmoud Alatrash — Thu, 05 Feb 2026 22:15:47 +0000

From 0.3% Crash Rate to Zero: Production-Grade Performance

This is Part 3 of a 3-part series.

🔙 Catch up on the series:

Part 1: When SharedPreferences Fails (Resilience & Architecture)
Part 2: The JWT Token Incident (Security & Encryption)

Our cache now:

✅ Survives platform failures (Circuit Breaker → 0% crash rate)
✅ Prevents memory leaks (LRU Eviction → 52MB vs 380MB)
✅ Protects sensitive data (Hardware-backed encryption)

But when we launched to production, our telemetry showed new problems:

Metric	Status	Issue
Cache crashes	✅ 0%	Circuit breaker works!
Security vulnerabilities	✅ 0	Encryption works!
Login sync time (50 items)	❌ 2.5s	Users frustrated
Large batch operations	❌ CRASH	`TransactionTooLargeException`
UI reactivity	❌ Stale	Profile photo update doesn't refresh screen

These aren't architecture problems—they're operational problems.

Production exposed three critical gaps:

Performance: Sequential writes are too slow. Naive parallelism crashes the app.
Concurrency: Race conditions cause data loss during TTL expiration.
Observability: Cache updates don't trigger UI updates (stale state).

In this part, we'll solve production-scale challenges:

⚡ Performance: Chunked batching to respect platform limits (1MB Binder, XPC constraints)
⚡ Concurrency: Optimistic Locking to prevent race conditions (version-based atomic operations)
⚡ Reactivity: Observer Pattern to make cache changes trigger UI updates
⚡ Monitoring: Production metrics and circuit breaker health checks
⚡ Quality: 3-layer testing strategy (unit, integration, widget tests)
⚡ Lessons Learned: What worked, what we'd change

By the end, you'll have a production-ready cache that handles millions of operations with zero downtime.

Full source code available on GitHub

Part 6: Performance - Batching Against Platform Limits

The Sequential Write Problem

When we first implemented setMultiple(), we took the straightforward approach:

@override
Future<void> setMultiple(
  Map<String, dynamic> items, {
  String? driver,
  Duration? ttl,
}) async {
  for (final entry in items.entries) {
    await set(entry.key, entry.value, driver: driver, ttl: ttl);
  }
}

This looks innocent. It's readable. It works.

But in production, when syncing 50 user preferences after login, we measured:

2.5 seconds on Android (Pixel 4a)
1.8 seconds on iOS (iPhone 11)

Each await blocks the next operation. With 50 items at ~50ms per write, you're looking at 2,500ms of sequential I/O.

The Naive Parallel Solution

Our first optimization attempt was obvious:

// WORSE: Unbounded Parallelism
await Future.wait(items.map((item) => cache.set(item.key, item.value)));

On paper, this should be 50x faster (50ms vs 2,500ms).

In reality:

✅ Local testing: 50 items in 120ms (20x improvement!)
❌ Production (Android): App crashes after 200+ items
❌ Production (iOS): Keychain access denied errors

Deep Dive: Why Unbounded Parallelism Crashes

Flutter communicates with native code via platform channels. These have undocumented hard limits:

Android (MethodChannel - Binder Transaction Limit):

Max concurrent calls: ~64
Transaction buffer: 1MB total
When exceeded: TransactionTooLargeException
Result: App crash

iOS (FlutterMethodChannel - XPC Limit):

Max concurrent calls: ~128
Message queue limit: Varies by iOS version
When exceeded: Dropped messages (silent failures!)
Result: Data loss without exceptions

When we launched 1,000 concurrent platform channel calls, we exhausted these system resources. The crash wasn't in our Dart code—it was in the native bridge layer.

Problem Breakdown:

Memory Exhaustion: Each Future holds:
- Serialized data (strings)
- Platform channel buffers (native memory)
- Event loop callbacks
- Stack frames

For 1,000 items, we saw 500MB+ memory spikes and GC pauses causing UI jank.

Platform Channel Saturation: The Android Binder has a 1MB transaction buffer limit shared across all IPC. iOS XPC has similar constraints. When exceeded, writes silently fail without throwing exceptions.
Secure Storage Rate Limiting:
- iOS Keychain: ~100 writes/second (error: errSecInteractionNotAllowed -25308)
- Android KeyStore: ~50 writes/second (error: android.security.KeyStoreException)

These aren't documented by Flutter or the platform vendors—we discovered them through production telemetry and crash reports.

Understanding Platform Limits

Android Binder Transaction Buffer:

The Binder buffer is shared across all system services (not just your app). If another app is also using Binder heavily, your app's available buffer shrinks.

iOS XPC Message Limits:

┌────────────────────────────────────────┐
│  XPC Message Queue (per connection)    │
├────────────────────────────────────────┤
│ Message 1: Keychain write              │
│ Message 2: Keychain write              │
│ ...                                    │
│ Message 128: Keychain write            │
├────────────────────────────────────────┤
│ Total: ~128 messages in flight         │
│ Message 129: DROPPED (no error!) ❌     │
└────────────────────────────────────────┘

XPC drops messages instead of crashing. This means data loss without any visible exception in your Dart code.

The Solution: Chunked Parallel Writes

After profiling across 15 device models, we found the sweet spot:

Future<void> setMultiple(
  Map<String, dynamic> items, {
  String? driver,
  Duration? ttl,
}) async {
  // Tune per platform and driver type
  final chunkSize = _getOptimalChunkSize(driver);
  final entries = items.entries.toList();

  for (var i = 0; i < entries.length; i += chunkSize) {
    final chunk = entries.skip(i).take(chunkSize);

    // Parallel within chunk, sequential between chunks
    await Future.wait(
      chunk.map((entry) => 
        set(entry.key, entry.value, driver: driver, ttl: ttl)
      )
    );
  }
}

int _getOptimalChunkSize(String? driver) {
  switch (driver) {
    case 'secure_storage':
      return 10;  // Keychain/KeyStore rate limits
    case 'shared_prefs':
      return 50;  // Disk I/O sweet spot
    case 'memory':
      return 100; // CPU-bound, can go higher
    default:
      return 50;  // Conservative default
  }
}

Why This Works:

Memory-Bounded: Only N futures in flight at once (vs unbounded)
Platform-Safe: Stays under Binder/XPC channel limits
Rate-Limit Compliant: Respects native storage throttling
Back-Pressure: Chunks act as natural flow control

Visualizing the Chunking Strategy

Sequential (Original):

Production Results:

Scenario	Sequential	Naive Parallel	Chunked Parallel
50 items (shared_prefs)	2,500ms	120ms	140ms ✅
500 items (shared_prefs)	25,000ms	CRASH ❌	1,200ms ✅
50 items (secure_storage)	12,000ms	ERROR ❌	2,500ms ✅
1,000 items (memory)	8,000ms	180ms*	120ms ✅

*Naive parallel succeeded in memory driver but used 400MB RAM

Architectural Insight: This is a classic distributed systems problem applied to mobile. In backend systems, you use circuit breakers and bulkheads to prevent cascading failures. On mobile, the constraint isn't network latency—it's shared OS resources (memory, file handles, Keychain locks).

Chunking is our bulkhead pattern. It isolates failures:

If chunk 5 fails, chunks 1-4 succeeded
We can retry chunk 5 without redoing all work
Memory pressure is predictable and bounded

Benchmarking Chunk Sizes

We benchmarked different chunk sizes on various device tiers:

SharedPreferences Driver:

Chunk Size	50 items	500 items	1,000 items	Memory Peak
10	180ms	2,100ms	4,300ms	45MB
25	152ms	1,450ms	2,800ms	78MB
50	140ms	1,200ms	2,350ms	95MB
100	138ms	CRASH	CRASH	180MB

SecureStorage Driver:

Chunk Size	50 items	500 items	Memory Peak
5	3,200ms	35,000ms	42MB
10	2,500ms	26,000ms	58MB
20	2,450ms	ERROR	95MB
50	ERROR	ERROR	-

Key Findings:

SharedPrefs: 50 items/chunk optimal (disk I/O saturates after this)
SecureStorage: 10 items/chunk optimal (Keychain rate-limits kick in)
Memory: 100 items/chunk optimal (pure CPU, no I/O bottleneck)

Part 8: The Observer Pattern - Making Cache Observable

The Problem: Stale UI State

Traditional caches are black boxes:

Widget A updates the cache
Widget B still shows old data
You have to manually refresh Widget B

This leads to stale UI and bugs like:

User updates profile photo → API succeeds → Cache updates → Profile screen doesn't refresh
Settings changed → Cache updated → App still uses old settings

The Solution: Reactive Events (Pub/Sub)

We implemented an Observer Pattern using Dart Streams:

// lib/core/cache/domain/events/cache_event.dart
enum CacheEventType {
  created,
  updated,
  removed,
  expired,
  cleared,
}

class CacheEvent {
  final String key;
  final CacheEventType type;
  final dynamic value;
  final dynamic oldValue;
  final DateTime timestamp;

  const CacheEvent({
    required this.key,
    required this.type,
    this.value,
    this.oldValue,
    required this.timestamp,
  });

  bool get isCreated => type == CacheEventType.created;
  bool get isUpdated => type == CacheEventType.updated;
  bool get isRemoved => type == CacheEventType.removed;
  bool get isExpired => type == CacheEventType.expired;
}

Implementation:

// lib/core/cache/utils/cache_subscription_manager.dart
class CacheSubscriptionManager {
  final Map<String, StreamController<CacheEvent>> _controllers = {};

  Stream<T?> watch<T>(String key) {
    _controllers.putIfAbsent(
      key,
      () => StreamController<CacheEvent>.broadcast(),
    );

    return _controllers[key]!.stream.map((event) => event.value as T?);
  }

  void notify(CacheEvent event) {
    _controllers[event.key]?.add(event);
  }

  void dispose(String key) {
    _controllers[key]?.close();
    _controllers.remove(key);
  }
}

Integration with Cache Operations

Every cache mutation triggers an event:

@override
Future<void> set<T>(String key, T value, {String? driver, Duration? ttl}) async {
  // Get old value for event
  dynamic oldValue;
  try {
    oldValue = await get<T>(key, driver: driver);
  } catch (_) {
    // Key doesn't exist yet
  }

  // Perform write
  final targetDriver = _manager.getDriver(driver);
  final serialized = CacheSerializer.serialize(value);
  await targetDriver.set(key, serialized);

  // Set TTL if provided
  if (ttl != null && _config?.enableTTL == true) {
    _ttl.set(key, ttl);
  }

  // Notify subscribers
  _subscriptions.notify(CacheEvent(
    key: key,
    type: oldValue == null ? CacheEventType.created : CacheEventType.updated,
    value: value,
    oldValue: oldValue,
    timestamp: DateTime.now(),
  ));
}

Usage in UI:

class ProfileScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return StreamBuilder<User?>(
      stream: Cache.watch<User>('current_user'),
      builder: (context, snapshot) {
        if (!snapshot.hasData) return CircularProgressIndicator();

        final user = snapshot.data!;
        return Column(
          children: [
            CircleAvatar(backgroundImage: NetworkImage(user.photoUrl)),
            Text(user.name),
          ],
        );
      },
    );
  }
}

// Anywhere in the app:
await Cache.set('current_user', updatedUser);
// ↑ This automatically triggers the StreamBuilder to rebuild!

How Broadcast Streams Work

We use StreamController.broadcast() instead of regular streams:

// Regular stream (single listener)
final controller = StreamController<CacheEvent>();
controller.stream.listen((event) { }); // OK
controller.stream.listen((event) { }); // ERROR: Already has listener

// Broadcast stream (multiple listeners)
final controller = StreamController<CacheEvent>.broadcast();
controller.stream.listen((event) { }); // OK
controller.stream.listen((event) { }); // OK - multiple listeners allowed

This allows:

Multiple widgets subscribing to the same cache key
Different parts of the app reacting to the same data changes
No coupling between widgets (they don't know about each other)

Real-World Usage Patterns

Pattern 1: Profile Photo Update

// ProfileEditScreen.dart
class ProfileEditScreen extends StatelessWidget {
  Future<void> _updatePhoto(File photo) async {
    // Upload to API
    final photoUrl = await api.uploadPhoto(photo);

    // Update user object
    final user = await Cache.get<User>('current_user');
    final updated = user.copyWith(photoUrl: photoUrl);

    // Cache update triggers all listeners
    await Cache.set('current_user', updated);

    // No need to manually update UI!
    // ProfileScreen automatically rebuilds via StreamBuilder
  }
}

// ProfileScreen.dart (automatically updates)
class ProfileScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return StreamBuilder<User?>(
      stream: Cache.watch<User>('current_user'),
      builder: (context, snapshot) {
        // Rebuilds when 'current_user' changes
        return CircleAvatar(
          backgroundImage: NetworkImage(snapshot.data!.photoUrl),
        );
      },
    );
  }
}

// AppDrawer.dart (also automatically updates)
class AppDrawer extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return StreamBuilder<User?>(
      stream: Cache.watch<User>('current_user'),
      builder: (context, snapshot) {
        // Also rebuilds when 'current_user' changes
        return DrawerHeader(
          child: CircleAvatar(
            backgroundImage: NetworkImage(snapshot.data!.photoUrl),
          ),
        );
      },
    );
  }
}

Pattern 2: Feature Flags

// Remote config updates feature flags
void onRemoteConfigFetched(Map<String, dynamic> flags) async {
  await Cache.set('feature_flags', flags);
  // All widgets watching 'feature_flags' rebuild automatically
}

// Multiple screens react
class HomeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return StreamBuilder<Map<String, dynamic>?>(
      stream: Cache.watch<Map<String, dynamic>>('feature_flags'),
      builder: (context, snapshot) {
        final flags = snapshot.data ?? {};

        if (flags['new_ui_enabled'] == true) {
          return NewHomeUI();
        }
        return LegacyHomeUI();
      },
    );
  }
}

This effectively turns our Cache into a lightweight State Management solution for global app data, similar to:

Redux/Riverpod (but simpler)
Provider (but with persistence)
GetX (but with Clean Architecture)

When to use Cache.watch() vs Provider/Riverpod:

Use Cache.watch() for: User session, app config, feature flags (data that needs persistence)
Use Provider/Riverpod for: UI state, form state, navigation state (ephemeral data)

Performance Considerations

Question: Won't this rebuild widgets too often?

Answer: No, because:

Dart Streams are lazy: StreamBuilder only listens when widget is mounted
Flutter rebuilds are cheap: Virtual DOM diffing makes unnecessary rebuilds fast
You control granularity: Subscribe to specific keys, not the entire cache

Benchmarks:

// Worst case: 1,000 cache writes/second
for (var i = 0; i < 1000; i++) {
  await Cache.set('counter', i);
}

// Result: StreamBuilder rebuilds 1,000 times
// Performance impact: ~5ms total (0.005ms per rebuild)
// UI remains smooth (60fps)

Flutter's virtual DOM diffing means if the actual UI output is identical, no expensive repaints occur.

Part 9: Optimistic Locking - Solving Race Conditions

The Race Condition Scenario

Consider this timeline with concurrent operations:

Time  Thread A                    Thread B
──────────────────────────────────────────────────
0ms   get('api_response')
1ms   → Sees TTL expired
2ms                                set('api_response', fresh_data)
3ms                                → Updates version to 1
4ms   remove('api_response')
5ms   → Deletes fresh data! ❌

Result: Thread A deletes the fresh data Thread B just wrote, causing data loss.

The Solution: Versioning with Optimistic Locking

We attached a version counter to every TTL entry:

// lib/core/cache/utils/cache_ttl.dart
class TTLEntry {
  final DateTime expiresAt;
  final int version;

  TTLEntry(this.expiresAt, this.version);

  TTLEntry copyWithNewVersion() => TTLEntry(expiresAt, version + 1);
}

class CacheTTL {
  final Map<String, TTLEntry> _ttlMap = {};
  int _globalVersion = 0;

  void set(String key, Duration ttl) {
    _ttlMap[key] = TTLEntry(DateTime.now().add(ttl), _globalVersion++);
  }

  /// Check if expired and return entry for atomic operations
  TTLEntry? getIfExpired(String key) {
    if (!_ttlMap.containsKey(key)) return null;

    final entry = _ttlMap[key]!;
    if (DateTime.now().isAfter(entry.expiresAt)) {
      return entry; // Return entry with version for atomic check
    }
    return null;
  }

  /// Remove only if version matches (atomic operation)
  bool removeIfVersionMatches(String key, int version) {
    final entry = _ttlMap[key];

    // Atomic Check: Only delete if version hasn't changed
    if (entry != null && entry.version == version) {
      _ttlMap.remove(key);
      log('TTL EXPIRED (atomic): $key', name: 'Cache');
      return true;
    }

    return false; // Version changed, key was updated! Abort deletion.
  }
}

How it's used in CacheImpl:

@override
Future<T?> get<T>(String key, {String? driver}) async {
  // Check for expiration with atomic version tracking
  final expiredEntry = _ttl.getIfExpired(key);
  if (expiredEntry != null) {
    // Get value before removing for event notification
    dynamic lastValue;
    try {
      final targetDriver = _manager.getDriver(driver);
      final raw = await targetDriver.get(key);
      if (raw != null) {
        lastValue = CacheSerializer.deserialize<T>(raw);
      }
    } catch (_) {
      // Ignore errors when getting expired value
    }

    // Atomic removal - only if version hasn't changed
    if (_ttl.removeIfVersionMatches(key, expiredEntry.version)) {
      await _manager.getDriver(driver).remove(key);

      // Notify subscribers about expiration
      _subscriptions.notify(CacheEvent(
        key: key,
        type: CacheEventType.expired,
        oldValue: lastValue,
        timestamp: DateTime.now(),
      ));

      throw CacheTTLExpiredException(
        key: key,
        expiredAt: expiredEntry.expiresAt,
      );
    }
    // else: Version changed, key was updated - continue to get fresh data
  }

  // ... rest of get() logic
}

Timeline with Optimistic Locking:

Time  Thread A                          Thread B
────────────────────────────────────────────────────────
0ms   get('api_response')
1ms   → Sees TTL expired (version 0)
2ms                                      set('api_response', fresh_data)
3ms                                      → Updates version to 1
4ms   removeIfVersionMatches(key, 0)
5ms   → Check fails (version is now 1) ✅
6ms   → Aborts deletion, returns fresh data

Result: Data consistency guaranteed, no data loss.

Understanding Optimistic Locking

Optimistic Locking assumes conflicts are rare, so it doesn't lock resources upfront. Instead:

Read data with version number
Process data (do work)
Write back only if version hasn't changed
Retry if version mismatch (conflict detected)

Compare to Pessimistic Locking:

// Pessimistic (traditional databases)
lock.acquire();  // Block other threads
final data = read('key');
process(data);
write('key', data);
lock.release();  // Allow other threads

Optimistic (our approach):

// No lock! Multiple threads can read simultaneously
final entry = getWithVersion('key');  // Read + version
process(entry.data);

// Only check version when writing
if (currentVersion == entry.version) {
  write('key', data);  // Success
} else {
  retry();  // Version changed, someone else updated it
}

Why Optimistic for Mobile?

No thread blocking: UI remains responsive (no frozen screens)
Better battery life: No spinning on locks
Conflicts are rare: Mobile apps usually have single-user, single-device access
Simpler code: No need for mutexes, semaphores, or deadlock prevention

This is the same pattern used in:

Database transactions (Optimistic Concurrency Control)
Version control systems (Git merge conflicts)
Distributed caches (Redis WATCH command)
RESTful APIs (ETags for conditional updates)

When Optimistic Locking Fails (and How to Handle It)

Scenario: High Contention

// 10 threads all trying to update the same key
for (var i = 0; i < 10; i++) {
  Future(() async {
    final entry = _ttl.getIfExpired('hot_key');
    // ... do work ...
    final success = _ttl.removeIfVersionMatches('hot_key', entry.version);
    if (!success) {
      // Version changed - retry
      await Future.delayed(Duration(milliseconds: 10));
      // Retry logic here
    }
  });
}

When does this happen in production?

Background sync + user action on same data
Multiple API calls updating same cache key
TTL expiration + manual refresh simultaneously

Solution: Exponential Backoff

Future<T?> getWithRetry<T>(String key, {int maxRetries = 3}) async {
  for (var attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await get<T>(key);
    } on CacheTTLExpiredException {
      if (attempt == maxRetries - 1) rethrow;

      // Exponential backoff: 10ms, 20ms, 40ms
      await Future.delayed(Duration(milliseconds: 10 * (1 << attempt)));
    }
  }
  return null;
}

Part 13: Production Metrics & Monitoring

We built a health check endpoint that exposes system status:

@override
Future<Map<String, dynamic>> stats() async {
  final stats = <String, dynamic>{
    'defaultDriver': _manager.defaultDriver,
    'availableDrivers': _manager.drivers.keys.map((k) => k.value).toList(),
    'driverHealth': _manager.driverHealth,
    'memorySize': await size(driver: 'memory'),
    'sharedPrefsSize': await size(driver: 'shared_prefs'),
    'secureStorageSize': await size(driver: 'secure_storage'),
    'config': _manager.config.toString(),
  };

  return stats;
}

Example output:

{
  "defaultDriver": "shared_prefs",
  "availableDrivers": ["memory", "shared_prefs", "secure_storage"],
  "driverHealth": {
    "memory": true,
    "shared_prefs": false,
    "secure_storage": true
  },
  "memorySize": 42,
  "sharedPrefsSize": 0,
  "secureStorageSize": 3,
  "config": "CacheConfig(ttl: true, maxKeyLength: 250, logFallbacks: true)"
}

Monitoring Strategy:

void main() async {
  await Cache.initialize(config: CacheConfig.defaults());

  // Send cache health to analytics on app launch
  final stats = await Cache.stats();
  Analytics.track('cache_health', stats);

  // Alert if SharedPrefs circuit is open
  if (stats['driverHealth']['shared_prefs'] == false) {
    Analytics.track('cache_circuit_breaker_triggered', {
      'driver': 'shared_prefs',
      'fallback': 'memory',
    });
  }

  runApp(MyApp());
}

Production Value:

A spike in shared_prefs: false alerts us to platform-specific issues before users complain. We can correlate with:

Device models (Pixel 6 Pro having issues?)
OS versions (Android 14 bug?)
App versions (Did our last update break something?)

Key Metrics to Track

1. Circuit Breaker State:

driver_availability_rate: % of time each driver is available
fallback_events_count: How often fallbacks occur
circuit_open_duration: How long circuits stay open

2. Performance Metrics:

cache_hit_rate: % of successful cache retrievals
cache_miss_rate: % of cache misses (fetch from source)
avg_read_latency: Average time for get() operations
avg_write_latency: Average time for set() operations

3. Memory Metrics:

lru_evictions_count: How often LRU evicts entries
memory_cache_size: Current number of entries in memory
memory_pressure_events: iOS memory warnings received

4. Error Metrics:

serialization_errors: Malformed data count
ttl_expirations: How many items expire (vs manually removed)
keystore_failures: Secure storage access failures

Alerting Rules

Critical Alerts:

if (stats['driverHealth']['shared_prefs'] == false) {
  // Circuit breaker triggered - disk storage down
  sendAlert('P1: Cache degraded to memory-only mode');
}

if (stats['memorySize'] > 5000) {
  // LRU limit might be too high for device
  sendAlert('P2: Memory cache approaching limit');
}

if (errorRate > 0.01) {
  // More than 1% of operations failing
  sendAlert('P1: Cache error rate elevated');
}

Warning Alerts:

if (cacheHitRate < 0.80) {
  // Low hit rate = users fetching from network too often
  sendAlert('P3: Cache hit rate below 80%');
}

if (avgWriteLatency > 500) {
  // Slow writes = poor UX
  sendAlert('P3: Cache write latency elevated');
}

Part 14: Testing Architecture - From Theory to Practice

One of the biggest benefits of this Clean Architecture approach is testability. We employ a 3-Layer Testing Strategy.

Layer 1: Unit Tests (Domain Logic - Pure Dart)

Testing pure logic without mocking platform channels or Flutter framework.

Testing Optimistic Locking for Race Conditions:

import 'package:flutter_test/flutter_test.dart';
import 'package:flutter_production_architecture/core/cache/utils/cache_ttl.dart';

void main() {
  group('CacheTTL - Optimistic Locking', () {
    late CacheTTL ttl;

    setUp(() {
      ttl = CacheTTL(enabled: true);
    });

    test('Race condition: Stale version should not delete fresh data', () {
      // Simulate two threads operating on the same key

      // Thread A: Set key with TTL of 1 second (version 0)
      ttl.set('api_response', Duration(seconds: 1));

      // Capture the expired entry info (what Thread A sees)
      final expiredEntry = ttl.getIfExpired('api_response');
      expect(expiredEntry, isNull); // Not expired yet

      // Simulate time passing (thread A goes to check expiration)
      // Meanwhile, Thread B updates the key with fresh data
      ttl.set('api_response', Duration(seconds: 10)); // version 1

      // Now Thread A finally checks expiration (after network delay)
      // Thread A tries to remove with its stale version (0)
      final removed = ttl.removeIfVersionMatches('api_response', 0);

      // Should FAIL because version is now 1 (Thread B updated it)
      expect(removed, false);

      // The key should still exist with fresh TTL
      expect(ttl.isExpired('api_response'), false);
    });

    test('Successful removal when version matches', () async {
      ttl.set('key', Duration(milliseconds: 10));

      // Wait for expiration
      await Future.delayed(Duration(milliseconds: 50));

      final expiredEntry = ttl.getIfExpired('key');
      expect(expiredEntry, isNotNull);

      // Remove with correct version
      final removed = ttl.removeIfVersionMatches('key', expiredEntry!.version);
      expect(removed, true);

      // Entry should be gone
      expect(ttl.isExpired('key'), false); // No longer tracked
    });
  });
}

Why this matters: This test documents our architectural decision better than any comment could. It proves the race condition is handled correctly.

Layer 2: Integration Tests (Data Layer - Platform Interaction)

Testing the Circuit Breaker logic by simulating platform failures.

import 'package:flutter_test/flutter_test.dart';
import 'package:shared_preferences/shared_preferences.dart';
import 'package:flutter_production_architecture/core/cache/data/repositories/cache_repository_impl.dart';
import 'package:flutter_production_architecture/core/cache/domain/entities/cache_config.dart';

void main() {
  group('CacheImpl - Circuit Breaker', () {
    test('Falls back to memory when SharedPreferences write fails', () async {
      // Arrange: Create a cache with default driver = shared_prefs
      SharedPreferences.setMockInitialValues({}); // Start clean
      final cache = await CacheImpl.create(
        defaultDriver: 'shared_prefs',
        config: CacheConfig(logFallbacks: true),
      );

      // In a real scenario, SharedPreferences might fail due to:
      // - Disk full
      // - Permissions error
      // - Corrupt storage
      // Our circuit breaker catches this and falls back to memory

      // Act: Write to cache
      await cache.set('test_key', 'test_value');

      // Assert: Data should be retrievable (from memory fallback if needed)
      final value = await cache.get<String>('test_key');
      expect(value, 'test_value');

      // Verify circuit breaker health
      final stats = await cache.stats();
      expect(stats['driverHealth'], isNotNull);
    });

    test('Memory driver always works as last resort', () async {
      final cache = await CacheImpl.create(defaultDriver: 'memory');

      // Memory driver should never fail
      await cache.set('key', 'value');
      final value = await cache.get<String>('key');

      expect(value, 'value');
    });
  });
}

Production bugs this caught:

Disk full errors on devices with <500MB free space
SharedPreferences corruption after force-stop during write
SecureStorage unavailable on Android emulators without Google Play Services

The circuit breaker prevented 100% of potential cache crashes.

Layer 3: Widget Tests (Presentation Layer - UI Reactivity)

Testing if the UI reacts to cache changes via the Observer Pattern.

import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:flutter_production_architecture/core/cache/presentation/cache_facade.dart';

void main() {
  group('Cache Subscriptions - Widget Updates', () {
    testWidgets('Widget rebuilds when subscribed cache key changes', (tester) async {
      // Arrange: Create a test app with a widget that subscribes to cache
      await tester.pumpWidget(
        MaterialApp(
          home: Scaffold(
            body: Builder(
              builder: (context) {
                return StreamBuilder<String?>(
                  stream: Cache.watch<String>('user_name'),
                  builder: (context, snapshot) {
                    return Text(snapshot.data ?? 'No user');
                  },
                );
              },
            ),
          ),
        ),
      );

      // Initial state
      expect(find.text('No user'), findsOneWidget);

      // Act: Update cache
      await Cache.set('user_name', 'Alice');
      await tester.pump(); // Process the stream event

      // Assert: Widget should reflect new value
      expect(find.text('Alice'), findsOneWidget);
      expect(find.text('No user'), findsNothing);

      // Act: Update again
      await Cache.set('user_name', 'Bob');
      await tester.pump();

      // Assert: Should show updated value
      expect(find.text('Bob'), findsOneWidget);
      expect(find.text('Alice'), findsNothing);
    });

    testWidgets('Multiple widgets can subscribe to the same key', (tester) async {
      await tester.pumpWidget(
        MaterialApp(
          home: Column(
            children: [
              StreamBuilder<String?>(
                stream: Cache.watch<String>('count'),
                builder: (context, snapshot) => Text('Widget1: ${snapshot.data ?? "0"}'),
              ),
              StreamBuilder<String?>(
                stream: Cache.watch<String>('count'),
                builder: (context, snapshot) => Text('Widget2: ${snapshot.data ?? "0"}'),
              ),
            ],
          ),
        ),
      );

      // Both should start at default
      expect(find.text('Widget1: 0'), findsOneWidget);
      expect(find.text('Widget2: 0'), findsOneWidget);

      // Update cache
      await Cache.set('count', '42');
      await tester.pump();

      // Both should update
      expect(find.text('Widget1: 42'), findsOneWidget);
      expect(find.text('Widget2: 42'), findsOneWidget);
    });
  });
}

Real bug this caught: User updates their profile photo → API call succeeds → Cache updates → Profile screen doesn't refresh (shows old photo). We forgot to subscribe the widget to cache changes. This test would have prevented the bug from reaching production.

Coverage Targets

flutter test --coverage
genhtml coverage/lcov.info -o coverage/html
open coverage/html/index.html

Our targets:

Domain layer (cache_ttl.dart, cache_validator.dart): 100% coverage ✅
Data layer (cache_repository_impl.dart): 95%+ coverage ✅
Presentation layer (cache_facade.dart): 80%+ coverage ✅

What we DON'T test:

Platform plugin code (SharedPreferences, SecureStorage) - trust the package maintainers
Flutter framework internals (StreamBuilder) - trust the Flutter team

Key Insight: Tests are executable documentation. When someone asks "Why optimistic locking?", the answer is: "Run the race condition test. Watch it fail without locking, pass with it."

Part 15: Lessons Learned - What We'd Do Differently

What Worked Well ✅

Circuit Breaker Pattern:
- Zero cache-related crashes in 8+ months of production
- Graceful degradation on 100% of storage failures
Interface Segregation (Clean Architecture):
- Unit tests run in 5ms instead of 500ms (no platform channels)
- Business logic is 100% platform-independent
Optimistic Locking:
- Eliminated race conditions in high-concurrency flows
- No data loss in TTL expiration scenarios
LRU Eviction:
- Memory stable at 52MB vs 380MB before
- 0% OOM crashes from unbounded cache growth
Observable Cache:
- UI automatically syncs with cache changes
- Replaced need for separate state management in many cases

What We'd Improve 🔧

Compression:
- Problem: Large JSON payloads (10KB+) waste disk space
- Future Solution: Add Gzip compression for values >5KB
- Implementation: Transparent in CacheSerializer
- Trade-off: 15% CPU overhead for 70% space savings
Encryption-at-Rest:
- Problem: Only SecureStorage is encrypted. SharedPrefs is plain text.
- Future Solution: Encrypt SharedPreferences data by default
- Trade-off: Performance hit (5ms → 15ms per operation)
- API: CacheConfig(encryptSharedPrefs: true)
Cache Warming:
- Problem: App starts cold, critical data loaded on-demand
- Future Solution: Preload critical data during splash screen
- Implementation:
```
 await Cache.warmup(['current_user', 'app_config', 'feature_flags']);
```
Selective Eviction:
- Problem: LRU evicts by access time, not importance
- Future Solution: Priority-based eviction (pin critical keys)
- API:
```
 await Cache.set('user', user, priority: CachePriority.high);
```
Cross-Tab Synchronization:
- Problem: Multiple instances (web) don't sync cache changes
- Future Solution: Use BroadcastChannel (web) or IsolateChannel (mobile)

Part 16: Putting It All Together - Complete Usage Guide

Basic CRUD Operations

// Initialize once in main()
await Cache.initialize(config: CacheConfig.defaults());

// Store data (auto-serialized)
await Cache.set<User>('current_user', user);
await Cache.set<List<String>>('tags', ['flutter', 'dart', 'mobile']);

// Retrieve data (type-safe)
final user = await Cache.get<User>('current_user');
final tags = await Cache.get<List<String>>('tags');

// Check existence
if (await Cache.has('current_user')) {
  print('User cached');
}

// Remove data
await Cache.remove('current_user');

// Clear all
await Cache.clear();

Secure Storage (Encrypted)

// Automatically uses FlutterSecureStorage (Keychain/KeyStore)
await Cache.secure.set('jwt_token', 'abc123');
await Cache.secure.set('api_key', 'sk_live_...');

// Retrieve
final token = await Cache.secure.get<String>('jwt_token');

// Remove
await Cache.secure.remove('jwt_token');

TTL (Time-To-Live)

// Cache with 1-hour expiration
await Cache.set('api_response', response, ttl: Duration(hours: 1));

// After 1 hour, this throws CacheTTLExpiredException
try {
  final response = await Cache.get('api_response');
} on CacheTTLExpiredException catch (e) {
  print('Data expired at: ${e.expiredAt}');
  // Fetch fresh data
}

Observable Cache (Reactive UI)

// Subscribe to changes
Cache.watch<User>('current_user').listen((user) {
  print('User updated: ${user?.name}');
});

// Update from anywhere
await Cache.set('current_user', updatedUser);
// ↑ All subscribers automatically notified!

// Use in widgets
class ProfileWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return StreamBuilder<User?>(
      stream: Cache.watch<User>('current_user'),
      builder: (context, snapshot) {
        if (!snapshot.hasData) return CircularProgressIndicator();
        return Text(snapshot.data!.name);
      },
    );
  }
}

Error Handling

try {
  final user = await Cache.get<User>('user');
} on CacheMissException {
  // Key doesn't exist - fetch from API
  final user = await api.fetchUser();
  await Cache.set('user', user);
} on CacheTTLExpiredException catch (e) {
  // Data expired - refresh it
  print('Expired at: ${e.expiredAt}');
  final user = await api.fetchUser();
  await Cache.set('user', user, ttl: Duration(hours: 1));
} on CacheSerializationException catch (e) {
  // Data corrupt - clear and refetch
  print('Corrupt data for type: ${e.type}');
  await Cache.remove('user');
  final user = await api.fetchUser();
  await Cache.set('user', user);
} on CacheDriverException catch (e) {
  // Storage failed - circuit breaker already handled this
  print('Driver ${e.driverName} failed, using fallback');
}

Batch Operations

// Write multiple items efficiently (chunked)
await Cache.setMultiple({
  'user': user,
  'settings': settings,
  'theme': theme,
  // ... up to 1,000+ items
});

// Read multiple items
final results = await Cache.getMultiple<String>(['key1', 'key2', 'key3']);
// Returns: {'key1': 'value1', 'key2': null, 'key3': 'value3'}

Health Monitoring

final stats = await Cache.stats();
print(stats);
// {
//   'defaultDriver': 'shared_prefs',
//   'driverHealth': {'memory': true, 'shared_prefs': true, 'secure_storage': true},
//   'memorySize': 42,
//   'sharedPrefsSize': 128,
//   'secureStorageSize': 3
// }

Conclusion: From Prototype to Production

When we started this journey, we asked: "Why does SharedPreferences fail in production?"

The answer: Because production systems require resilience, security, and scale—not just functionality.

What we built across this 3-part series:

Part 1: Resilience

✅ Circuit Breaker Pattern (0% crash rate from cache failures)
✅ LRU Eviction (52MB vs 380MB memory usage)
✅ Clean Architecture (100% testable domain logic)
✅ Strategy Pattern (swappable storage backends)
✅ Type-safe serialization (automatic JSON handling)

Part 2: Security

✅ Hardware-backed encryption (iOS Keychain, Android KeyStore)
✅ Tiered storage strategy (public vs secure cache)
✅ Defense-in-depth (protection against root, forensics, malware)
✅ Security-aware exceptions (meaningful error handling)

Part 3: Scale & Quality

✅ Chunked batching (140ms vs 2.5s for 50 items)
✅ Optimistic Locking (zero race condition data loss)
✅ Observable cache (reactive UI updates via Observer Pattern)
✅ Production metrics (circuit breaker health monitoring)
✅ 3-layer testing (95%+ coverage across domain/data/presentation)

Production Impact Summary

Metric	Before	After	Improvement
Cache-related crashes	0.3%	0.0%	100% reduction
Memory usage (8h session)	380MB	52MB	86% reduction
Sync time (50 items)	2,500ms	140ms	94% faster
Race condition data loss	Occasional	0	Eliminated
Security vulnerabilities	P0 Critical	0	Compliant
Test coverage	~40%	95%+	2.4x increase

Key Architectural Insights

The patterns here aren't Flutter-specific—they're systems engineering applied to mobile:

Circuit Breakers (used by Netflix, AWS)
LRU Eviction (used by Redis, CPU caches)
Optimistic Locking (used by databases, Git)
Observer Pattern (used by reactive frameworks everywhere)
Strategy Pattern (used by payment gateways, storage engines)

Mobile platforms have unique constraints:

Shared OS resources (Binder, XPC)
Hardware-backed security (Secure Enclave, TrustZone)
Memory pressure (iOS jetsam, Android OOM killer)
User expectations (instant UI, offline-first)

Our architecture respects these constraints while applying battle-tested patterns from distributed systems.

What's Next for Your Implementation

If you're implementing this in your app:

Start with Part 1: Get the Circuit Breaker and LRU working first
Add Part 2 Security: Identify sensitive keys (tokens, keys) → move to SecureStorage
Optimize with Part 3: Profile your batch operations → add chunking if needed

Beyond this series (future enhancements):

Compression for large payloads (Gzip for >5KB values)
Priority-based eviction (pin critical keys, evict less important ones first)
Cross-tab synchronization (BroadcastChannel for web, IsolateChannel for mobile)
Encryption-at-rest for SharedPreferences (EncryptedSharedPreferences by default)
Cache warming (preload critical data during splash screen)

Resources

Full Source Code:

🐙 Flutter Production Architecture on GitHub

Read the Series:

📖 Part 1: When SharedPreferences Fails (Resilience)
📖 Part 2: The JWT Token Incident (Security)
📖 Part 3: From 0.3% Crash Rate to Zero (Performance) ← You are here

Further Reading:

If this series helped you:

⭐ Star the GitHub repository
💬 Share your implementation experiences in the comments
🔗 Share with your team (especially those fighting SharedPreferences bugs!)

Questions or improvements? Open an issue or PR on the GitHub repo. This is a living architecture—feedback makes it better.

Tags: #Flutter #Architecture #SystemDesign #Production #Mobile #CleanArchitecture #Performance #Testing

Author: DevMatrash

Date: February 2026

The JWT Token Incident: Why Your Flutter App's Cache Isn't Secure (And How to Fix It)

Mahmoud Alatrash — Thu, 05 Feb 2026 22:13:41 +0000

The JWT Token Incident: Why Your Flutter Cache Isn't Secure

This is Part 2 of a 3-part series.

🔙 Missed Part 1? Read When SharedPreferences Fails: Architecting Resilient Cache Infrastructure where we built the fault-tolerant foundation with Circuit Breakers and LRU Eviction.

Here's what we built so far:

✅ Fault-tolerant storage with automatic fallbacks
✅ Memory-efficient LRU eviction (52MB vs 380MB)
✅ Type-safe serialization and clean interfaces

But resilience doesn't mean security.

During our pre-production security audit, a pentester showed us how to extract every JWT token, API key,
and user credential from our "secure" app—in under 60 seconds:

adb shell
cat /data/data/com.yourapp/shared_prefs/FlutterSharedPreferences.xml

Everything was in plain text.

The auditor then used the extracted JWT token to authenticate API requests from Postman and access user
private data. Finding: P0 Critical - Authentication tokens stored unencrypted.

The threat model was clear:

❌ SharedPreferences: Plain text XML (exposed on rooted devices)
❌ ADB backups: Include SharedPrefs by default (no root required)
❌ Forensic tools: Can extract plain text data even from powered-off devices

In this part, we'll architect a defense-in-depth security layer:

🔐 Understanding iOS Keychain and Android KeyStore (hardware-backed encryption)
🔐 How Secure Enclave and TrustZone protect keys even on rooted devices
🔐 The 50-100x performance tax (and why it's worth it for tokens, not preferences)
🔐 Real-world attack scenarios (root access, ADB backups, forensic tools)
🔐 Exception design for security-aware error handling

By the end, you'll know exactly what to encrypt, how to encrypt it, and how to handle failures gracefully.

Full source code available on GitHub

Part 5: Security Architecture - When SharedPreferences Isn't Enough

The JWT Token Incident (Pre-Production Audit)

During our security audit, the pentester showed us this:

# On a rooted Android device
adb shell
cd /data/data/com.yourapp/shared_prefs/
cat FlutterSharedPreferences.xml

<?xml version="1.0" encoding="utf-8"?>
<map>
    <string name="flutter.jwt_token">eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...</string>
    <string name="flutter.api_key">sk_live_51HqK9...</string>
    <string name="flutter.user_email">user@example.com</string>
</map>

Everything was in plain text.

The auditor then demonstrated:

Extracting the JWT token
Using it to authenticate API requests from Postman
Accessing the user's private data

Finding: P0 Critical - Authentication tokens stored unencrypted.

Understanding the Threat Model

What SharedPreferences Protects Against:

✅ Other apps reading your data (sandboxed by OS)
✅ Accidental deletion (persists across app restarts)

What SharedPreferences DOES NOT Protect Against:

❌ Root/jailbreak access (user has full filesystem access)
❌ Device backup leaks (ADB backups include SharedPrefs by default)
❌ Malware with elevated permissions
❌ Physical device access (forensic tools like Cellebrite, GrayKey)
❌ Screenshot/screen recording attacks (if displayed in UI)

The Solution: Explicit Security Tiers

We designed the API to force a conscious decision about security:

// Tier 1: Public Cache (Fast, Non-Encrypted)
// For preferences, themes, and non-sensitive data
await Cache.set('theme_mode', 'dark');
await Cache.set('language', 'en');
await Cache.set('last_sync_timestamp', DateTime.now().toIso8601String());

// Tier 2: Secure Cache (Slow, Hardware-Encrypted)
// For sensitive data requiring encryption
await Cache.secure.set('jwt_token', token);
await Cache.secure.set('api_key', apiKey);
await Cache.secure.set('biometric_signature', signature);

Why explicit? We considered auto-detecting sensitive keys (e.g., if key contains "token" or "password"), but rejected it:

False positives: "password_hint" doesn't need encryption
False negatives: "auth" is vague—could be sensitive or not
Magic is dangerous: Security should be visible in code reviews

Platform Internals: How Secure Storage Works

iOS: Keychain Services Architecture

Key Properties:

Hardware-backed: Keys stored in Secure Enclave (isolated coprocessor)
Tied to device UID: Can't copy Keychain data to another device
Access control: Can require Face ID/Touch ID for key access
Persistence: Survives app reinstall (unless kSecAttrAccessibleWhenUnlockedThisDeviceOnly)
iCloud sync: Can be disabled to prevent cloud backup

What happens when you write to Keychain:

await secureStorage.write(key: 'jwt_token', value: token);

Behind the scenes:

Flutter plugin calls iOS Keychain API (SecItemAdd)
Keychain API sends request to securityd daemon (IPC via XPC)
securityd communicates with Secure Enclave
Secure Enclave generates encryption key (never leaves the coprocessor)
Data encrypted with AES-256-GCM
Encrypted blob stored in SQLite database at /var/Keychains/keychain-2.db
Encryption key remains in Secure Enclave (inaccessible to app)

Configuration:

const storage = FlutterSecureStorage(
  iOptions: IOSOptions(
    accessibility: KeychainAccessibility.first_unlock_this_device,
    // Data accessible after first device unlock, doesn't sync to iCloud
  ),
);

Accessibility Options:

Option	When Accessible	Survives Reboot?	iCloud Sync?	Use Case
`unlocked`	Device unlocked	✅ Yes	✅ Yes	User preferences
`unlocked_this_device`	Device unlocked	✅ Yes	❌ No	Session tokens
`first_unlock`	After first unlock	✅ Yes	✅ Yes	Background refresh tokens
`first_unlock_this_device`	After first unlock	✅ Yes	❌ No	Recommended for tokens
`passcode_set_this_device`	Passcode required	✅ Yes	❌ No	Extra sensitive data

We use first_unlock_this_device because:

Data survives device reboot (user doesn't need to re-login)
Data NOT synced to iCloud (no cloud backup exposure)
Background tasks can access after first unlock (push notifications work)

Android: KeyStore System Architecture

Key Properties:

Hardware-backed (when available): Uses ARM TrustZone (TEE) or StrongBox
Key isolation: Encryption keys never exposed to app process
Software fallback: On older devices (<API 23), keys stored in encrypted user storage
Root-resistant: Hardware-backed keys survive even on rooted devices (keys in TEE)

What happens when you write to SecureStorage on Android:

await secureStorage.write(key: 'jwt_token', value: token);

Behind the scenes (API 23+):

Flutter plugin uses EncryptedSharedPreferences
EncryptedSharedPreferences retrieves master key from KeyStore
If master key doesn't exist, KeyStore generates one in TrustZone
Data encrypted with AES-256-GCM using master key
Encrypted data stored in SharedPreferences XML
Master key never leaves TrustZone (hardware-isolated)

Under the hood (what gets written to disk):

<!-- /data/data/com.yourapp/shared_prefs/FlutterSecureStorage.xml -->
<string name="__androidx_security_crypto_encrypted_prefs_key_keyset__">
  AeS7K9mP2qL4vN8xR5tY1wZ3bC6dF... (encrypted with KeyStore master key)
</string>
<string name="__androidx_security_crypto_encrypted_prefs_value_keyset__">
  X2nQ8vL5jH4kM7pA9sD3fG6hJ0mN... (encrypted with KeyStore master key)
</string>
<string name="VGhpcyBpcyB0aGUgcHJlZml4IGZvciBhIGtleQ==">
  AeadAes256GcmHkdfSha256... (encrypted 'jwt_token' value)
</string>

Even if an attacker extracts this XML:

The data is encrypted (AES-256-GCM)
The encryption key is in TrustZone (hardware-isolated)
Without the device's hardware UID, the data is useless

Hardware Attestation:

On modern Android devices (API 24+), you can verify key storage:

final keyInfo = KeyFactory.getInstance(algorithm)
    .getKeySpec(key, KeyInfo.class);

if (keyInfo.isInsideSecureHardware()) {
  print('✅ Key protected by hardware (TrustZone/StrongBox)');
} else {
  print('⚠️ Key in software (older device or emulator)');
}

The Performance Tax

Secure storage is 50-100x slower than SharedPreferences:

Why so slow?

Cryptographic operations: AES-256 encryption/decryption on every call
Inter-process communication:
- iOS: XPC calls to securityd daemon (context switch)
- Android: Binder IPC to KeyStore service
Hardware round-trip: Calls into TrustZone or Secure Enclave require switching execution environments

The IPC Overhead:

Your App (Dart) → Flutter Plugin (Native) → System Service → Hardware → Response
     ↓                    ↓                        ↓             ↓
   5ms               20ms (context switch)      50ms        80ms (crypto)
                                                           ─────────
                                                           155ms total

Compare to SharedPreferences:

Your App (Dart) → Flutter Plugin (Native) → File I/O → Response
     ↓                    ↓                      ↓
   1ms                   2ms                   5ms
                                              ────
                                              8ms total

Real App Startup Performance:

// ❌ BAD: Loading everything from secure storage
await secureCache.get('user_id');        // 120ms
await secureCache.get('user_name');      // 115ms  
await secureCache.get('user_email');     // 118ms
await secureCache.get('jwt_token');      // 130ms
// Total: ~480ms (delays first screen render!)

// ✅ GOOD: Only secrets in secure storage
await cache.get('user_id');              // 3ms (SharedPrefs)
await cache.get('user_name');            // 2ms (SharedPrefs)
await cache.get('user_email');           // 3ms (SharedPrefs)
await secureCache.get('jwt_token');      // 125ms (SecureStorage)
// Total: ~133ms (72% faster!)

Decision Matrix: Which Driver to Use

// ✅ Use SharedPreferences (fast, plain text) for:
await Cache.set('user_preferences', json, driver: 'shared_prefs');
await Cache.set('cached_api_response', response, driver: 'shared_prefs');
await Cache.set('feature_flags', flags, driver: 'shared_prefs');
await Cache.set('theme_mode', 'dark', driver: 'shared_prefs');
// Characteristics: High-frequency access, non-sensitive, ok if exposed

// ✅ Use SecureStorage (slow, encrypted) for:
await Cache.set('jwt_token', token, driver: 'secure_storage');
await Cache.set('oauth_refresh_token', refresh, driver: 'secure_storage');
await Cache.set('credit_card_token', cardToken, driver: 'secure_storage');
await Cache.set('encryption_key', key, driver: 'secure_storage');
await Cache.set('biometric_signature', sig, driver: 'secure_storage');
// Characteristics: Low-frequency access, highly sensitive, must be encrypted

// ✅ Use Memory (fast, ephemeral) for:
await Cache.set('session_state', state, driver: 'memory');
await Cache.set('pagination_cursor', cursor, driver: 'memory');
await Cache.set('search_results', results, driver: 'memory');
// Characteristics: Temporary data, doesn't need persistence

// ❌ Never store in any driver:
// - Raw passwords (use hashing + secure storage for tokens only)
// - Social Security Numbers (store on backend only)
// - Full credit card numbers (use tokenization services like Stripe)
// - PII without user consent (GDPR/CCPA compliance)

Real-World Attack Scenarios We Protect Against

Attack 1: Rooted Device + Malware

# Attacker with root access
su
cat /data/data/com.yourapp/shared_prefs/*.xml
# ✅ SharedPrefs: Exposed (plain text XML)
# ✅ SecureStorage: Still encrypted (master key in hardware TEE)

Even with root, the attacker cannot extract the encryption keys from TrustZone/Secure Enclave.

Why hardware-backed encryption survives root:

Root access gives you:
✅ Read filesystem (all SharedPreferences XML)
✅ Inject code into running processes
✅ Modify system files

Root DOES NOT give you:
❌ Access to Secure Enclave/TrustZone (hardware-isolated)
❌ Extraction of KeyStore master keys (protected by hardware UID)
❌ Ability to decrypt data without proper hardware

Attack 2: ADB Backup Extraction (No Root Required)

# Attacker with physical device access (USB debugging enabled)
adb backup -f backup.ab com.yourapp
dd if=backup.ab bs=24 skip=1 | openssl zlib -d > backup.tar
tar xf backup.tar
cat apps/com.yourapp/sp/*.xml
# ✅ SharedPrefs: Exposed (included in backup by default)
# ✅ SecureStorage: Protected (excluded via android:allowBackup="false")

Protection strategy:

In AndroidManifest.xml:

<application
    android:allowBackup="false"
    android:fullBackupContent="false">

This prevents ADB backups from including app data. For user-requested backups, use Android Auto Backup with exclusion rules:

<!-- res/xml/backup_rules.xml -->
<full-backup-content>
    <exclude domain="sharedpref" path="FlutterSecureStorage.xml"/>
</full-backup-content>

Attack 3: Forensic Tools (Police/Government)

Professional forensic tools (Cellebrite UFED, GrayKey, Magnet AXIOM) can extract:

✅ SharedPreferences data (plain text, easy to parse)
✅ App databases (SQLite files)
✅ App files and media
❌ Keychain/KeyStore data without device passcode (hardware-protected)
❌ Data from powered-off devices (encryption keys in volatile memory)

How forensic tools work:

Physical extraction: Connect device via JTAG, exploit bootloader
Logical extraction: Use vendor debug protocols (iOS: lockdownd, Android: ADB)
Filesystem analysis: Parse SQLite, XML, binary files
Keychain/KeyStore attempt: Try to extract keys (requires device passcode)

What stops them:

iOS: Secure Enclave requires device passcode to release keys. Without passcode, Keychain is useless.
Android: TrustZone-backed keys require device unlock. StrongBox (Pixel 3+) adds hardware rate limiting (10 attempts/second max).

Defense in Depth: Security Layers

The security architecture is built on four defensive layers, forcing an attacker to bypass multiple distinct barriers:

Layer 1: App Sandbox
- Protection: Prevents other apps from reading data.
- Vulnerability: Can be bypassed by Root access or physical extraction.
Layer 2: Encrypted Storage (AES-256)
- Protection: Data is encrypted at rest on the disk.
- Vulnerability: Can be bypassed if the Master Key is extracted.
Layer 3: Hardware-Backed Keys
- Protection: Keys are isolated in Secure Enclave/TEE (Hardware level).
- Vulnerability: Extremely difficult to bypass (requires expensive hardware attacks).
Layer 4: Device Passcode + Biometrics
- Protection: User access control (Face ID, Touch ID).
- Vulnerability: Social engineering or biometric spoofing.

Each layer protects against a different threat vector. SecureStorage specifically protects against offline attacks (device lost/stolen, forensic analysis, malware).

Key Insight: Security architecture isn't about choosing "the secure option"—it's about matching threat models to controls. SharedPreferences is perfectly secure for themes and preferences. SecureStorage is essential for tokens and keys. The architecture makes this distinction explicit and code-reviewable.

Part 11: Exception Design - Meaningful Error Messages for Security

Generic exceptions (Exception: error) hide root causes and make debugging impossible. Security failures need explicit, actionable errors.

We implemented a specialized hierarchy:

// lib/core/cache/domain/exceptions/cache_exceptions.dart

/// Base exception for all cache operations
abstract class CacheException implements Exception {
  final String message;
  final Object? cause;
  final StackTrace? stackTrace;

  const CacheException({
    required this.message,
    this.cause,
    this.stackTrace,
  });

  @override
  String toString() =>
      '$runtimeType: $message${cause != null ? ' (caused by: $cause)' : ''}';
}

/// Key not found in cache
class CacheMissException extends CacheException {
  final String key;

  const CacheMissException({
    required this.key,
    String? message,
    super.cause,
    super.stackTrace,
  }) : super(message: message ?? 'Cache miss for key: $key');
}

/// Failed to serialize/deserialize data
class CacheSerializationException extends CacheException {
  final Type type;
  final dynamic value;

  const CacheSerializationException({
    required this.type,
    this.value,
    super.message = 'Failed to serialize/deserialize type',
    super.cause,
    super.stackTrace,
  });
}

/// Storage driver unavailable or failed
class CacheDriverException extends CacheException {
  final String driverName;

  const CacheDriverException({
    required this.driverName,
    super.message = 'Cache driver failure',
    super.cause,
    super.stackTrace,
  });
}

/// Data expired (TTL exceeded)
class CacheTTLExpiredException extends CacheException {
  final String key;
  final DateTime expiredAt;

  const CacheTTLExpiredException({
    required this.key,
    required this.expiredAt,
    String? message,
    super.cause,
    super.stackTrace,
  }) : super(message: message ?? 'Cache entry expired for key: $key');
}

Why Security-Aware Exceptions Matter

Scenario: Keychain Access Failure on iOS

Without specific exceptions:

try {
  final token = await secureCache.get('jwt_token');
} catch (e) {
  print('Error: $e'); // What went wrong? Keychain? Network? Bug?
  // User sees: "Something went wrong"
}

With security-aware exceptions:

try {
  final token = await secureCache.get('jwt_token');
} on CacheDriverException catch (e) {
  if (e.driverName == 'secure_storage') {
    // Keychain access failed
    if (e.cause.toString().contains('errSecInteractionNotAllowed')) {
      // Device is locked, background access denied
      showNotification('Please unlock your device to continue');
    } else if (e.cause.toString().contains('errSecAuthFailed')) {
      // User denied Face ID/Touch ID
      showAlert('Biometric authentication required');
    } else {
      // Generic Keychain failure - fall back to re-login
      logout();
      showAlert('Session expired. Please log in again.');
    }
  }
} on CacheTTLExpiredException catch (e) {
  // Token expired - refresh it
  final newToken = await api.refreshToken();
  await secureCache.set('jwt_token', newToken, ttl: Duration(hours: 1));
}

Common Keychain/KeyStore Error Codes

iOS Keychain Errors:

Error Code	Name	Meaning	Recovery Strategy
`-25300`	`errSecItemNotFound`	Key doesn't exist	Expected - user not logged in
`-25308`	`errSecInteractionNotAllowed`	Device locked	Wait for unlock, show notification
`-26275`	`errSecAuthFailed`	Biometric denied	Retry or fallback to passcode
`-34018`	(Undocumented)	iOS 10 Keychain bug	Known Apple bug - retry after delay

Android KeyStore Errors:

Exception	Meaning	Recovery Strategy
`KeyStoreException`	Generic failure	Log and fallback to re-login
`UserNotAuthenticatedException`	User auth required	Prompt for biometric/PIN
`KeyPermanentlyInvalidatedException`	Biometric changed	Clear all secure data, force re-login

Production Example: Handling KeyStore Failures

Future<String?> getSecureToken() async {
  try {
    return await Cache.secure.get<String>('jwt_token');
  } on CacheDriverException catch (e) {
    if (e.driverName == 'secure_storage') {
      // Log to analytics
      Analytics.track('keystore_failure', {
        'error': e.message,
        'platform': Platform.isIOS ? 'ios' : 'android',
      });

      // Check if we can recover
      if (e.cause is UserNotAuthenticatedException) {
        // User needs to authenticate
        final authenticated = await promptBiometric();
        if (authenticated) {
          // Retry after successful auth
          return await Cache.secure.get<String>('jwt_token');
        }
      }

      // Cannot recover - force re-login
      await logout();
      return null;
    }
    rethrow;
  }
}

Usage with specific error handling:

try {
  final user = await Cache.get<User>('current_user');
} on CacheMissException catch (e) {
  // Fetch from API
  final user = await api.fetchUser();
  await Cache.set('current_user', user);
} on CacheTTLExpiredException catch (e) {
  // Refresh expired data
  print('Data expired at: ${e.expiredAt}');
  final user = await api.fetchUser();
  await Cache.set('current_user', user, ttl: Duration(hours: 1));
} on CacheSerializationException catch (e) {
  // Data corrupt, clear it
  print('Corrupt data for type: ${e.type}');
  await Cache.remove('current_user');
} on CacheDriverException catch (e) {
  // Storage failed, use fallback
  print('Driver ${e.driverName} failed');
  // Circuit breaker already handled this, but we can log it
}

Production Benefit:

When looking at Crashlytics or Sentry, we can instantly distinguish between:

CacheSerializationException → Data corrupt, investigate data format changes
CacheDriverException(secure_storage) → Keychain failure, check OS version distribution
CacheMissException → Expected behavior (cache empty)
CacheTTLExpiredException → Expected behavior (data expired)

Security Insight: Exceptions are part of your attack surface. Don't leak sensitive information in error messages:

// ❌ BAD: Leaks token structure
throw Exception('Invalid JWT token: $token');

// ✅ GOOD: No sensitive data in message
throw CacheSerializationException(
  type: String,
  message: 'Invalid token format',
  // token not included in exception
);

What's Next: Scaling to Production

We've built a secure cache that protects sensitive data with hardware-backed encryption:

✅ JWT tokens encrypted in iOS Keychain (Secure Enclave)
✅ API keys protected in Android KeyStore (TrustZone)
✅ Defense-in-depth against root access, forensic tools, and malware
✅ Security-aware exception handling (CacheDriverException, etc.)
✅ Explicit tier separation (public vs secure cache)

But production systems face challenges beyond security:

What happens when you need to sync 500 user preferences after login?

Our first implementation:

❌ Sequential writes: 2.5 seconds (users staring at loading spinner)
❌ Naive parallel: App crashes after 200+ items (TransactionTooLargeException)
❌ Stale UI: User updates profile → cache updates → screen doesn't refresh

We had a secure cache. But it wasn't production-ready yet.

In Part 3, we'll tackle production-scale challenges:

⚡ Batching Against Platform Limits: Android Binder (1MB), iOS XPC constraints
⚡ Optimistic Locking: Solving race conditions with versioning
⚡ Observer Pattern: Making cache changes observable to UI (reactive state)
⚡ Production Metrics: Circuit breaker health checks and monitoring
⚡ Testing Architecture: 3-layer strategy (unit, integration, widget tests)
⚡ Lessons Learned: What worked, what we'd change

From 0.3% crash rate to zero. From 2.5 seconds to 140ms. From manual UI updates to reactive state.

This is where theory meets production.

📖 Continue to Part 3: From 0.3% Crash Rate to Zero: Scaling Flutter Cache with Batching & Locking

🐙 Star the repo: Flutter Production Architecture on GitHub

Tags: #Flutter #Security #Keychain #KeyStore #Encryption #Mobile #HardwareSecurity

When SharedPreferences Fails: Architecting Resilient Cache Infrastructure for Production Flutter Apps

Mahmoud Alatrash — Thu, 05 Feb 2026 22:12:31 +0000

The Problem: It Starts So Simply

You're building a Flutter app. You need to cache some data. You reach for shared_preferences.
Five minutes later, you've got a working prototype. Ship it, right?

Wrong.

Six months later, you're debugging why your app crashes on iOS Simulator, why SharedPreferences.getInstance()
randomly fails on some Android devices, and why your "secure" tokens are stored in plain text XML files.

This is Part 1 of a 3-part series on architecting fault-tolerant, secure, and scalable cache systems in Flutter.

In this part, we'll cover:

✅ Why SharedPreferences fails in production (and how to detect it)
✅ Circuit Breaker Pattern for zero-downtime degradation
✅ LRU Eviction to prevent memory leaks (from 380MB → 52MB)
✅ Clean Architecture principles for testable cache infrastructure
✅ Strategy Pattern for swappable storage backends
✅ Type-safe serialization with automatic JSON handling
✅ Configuration as code to avoid magic numbers

By the end of this guide, you'll have a cache system that survives platform failures, memory constraints,
and high-concurrency scenarios.

You can find the full source code in the Flutter Production Architecture repository.

🚀 Quick Start: The "Hands-on" Approach

Before we dive into the deep architecture, here's how easy it is to use the final system.

1. Setup (in `main.dart`)

Instead of a messy initialization, we use a clean configuration object:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Detect device capabilities
  final isLowEndDevice = (await getTotalMemory()) < 2 * 1024 * 1024 * 1024;

  // Initialize with environment-specific config
  await Cache.initialize(
    defaultDriver: 'shared_prefs',
    config: isLowEndDevice 
        ? CacheConfig.forLowMemoryDevices() 
        : CacheConfig.defaults(),
  );

  runApp(MyApp());
}

2. Usage (Type-Safe & Clean)

⛔ The Old Way (Fragile):

// You have to remember key names, handle nulls, and catch errors manually
try {
  final prefs = await SharedPreferences.getInstance();
  await prefs.setString('user', jsonEncode(user.toJson()));

  final json = prefs.getString('user');
  final user = json != null ? User.fromJson(jsonDecode(json)) : null;
} catch (e) {
  print('Crash!'); // No recovery strategy
}

✅ The New Architecture (Resilient):

// Type-safe, auto-serialized, and fault-tolerant
await Cache.set<User>('current_user', user);

// Retrieval with type safety
final user = await Cache.get<User>('current_user');

// Secure storage (auto-encrypted via Keychain/KeyStore)
await Cache.secure.set('api_token', 'xyz-123');

// Reactive listener (updates UI automatically via Observer Pattern)
Cache.watch<User>('current_user').listen((user) {
  print('User updated: ${user.name}');
});

Part 1: The Hidden Dangers of Platform Storage

Why SharedPreferences is a Landmine

Let's start with a harsh truth: SharedPreferences is not a reliable storage mechanism out of the box.

Here's what the Flutter documentation doesn't tell you:

// This looks innocent...
final prefs = await SharedPreferences.getInstance();
await prefs.setString('token', 'abc123');

// But this can fail in production:
// 1. iOS Simulator: "MissingPluginException"
// 2. Android: Plugin channel not registered yet
// 3. Platform channel timeout during cold start
// 4. Disk full errors (no space to write)
// 5. SharedPreferences corruption after force-stop during write

In production environments, initialization failures are rare but critical. A single failure here can crash the entire app bootstrap process. The naive approach crashes your app. The production approach? Graceful degradation with circuit breakers.

Part 2: Architecture Decisions - Clean Architecture Meets Mobile Reality

Layer Separation

Most Flutter architectures place caching logic inside Repositories. We moved it deeper. Cache is infrastructure, not business logic.

Our architecture follows Clean Architecture principles:

Key Insight: The domain layer is pure Dart - zero Flutter dependencies. This means:

Unit tests run in milliseconds (no async platform channels)
Business logic is portable to other platforms
Testing doesn't require mocking MethodChannels

The Layer Breakdown

lib/core/cache/
├── presentation/
│   └── cache_facade.dart                # Static API (Flutter-aware)
├── domain/
│   ├── entities/cache_config.dart       # Pure Dart value objects
│   ├── exceptions/cache_exceptions.dart # Domain exceptions
│   ├── events/cache_event.dart          # Domain events
│   ├── repositories/i_cache.dart        # Interface (contract)
│   └── strategies/cache_driver_strategy.dart
├── data/
│   ├── repositories/cache_repository_impl.dart # Concrete implementation
│   └── datasources/
│       ├── cache_drivers.dart           # Platform-specific drivers
│       ├── cache_manager.dart           # Orchestration
│       └── cache_storage.dart           # Serialization
└── utils/
    ├── cache_ttl.dart                   # TTL management
    ├── cache_validator.dart             # Validation
    └── cache_subscription_manager.dart  # Pub/Sub

Why this matters:

The domain layer (i_cache.dart, cache_config.dart) contains zero references to:

SharedPreferences
FlutterSecureStorage
MethodChannel
Any Flutter framework classes

This means:

Tests run 100x faster (no platform channel overhead)
Business logic is portable (could move to CLI, server, web without changes)
Dependencies point inward (domain doesn't know about Flutter)

Part 3: The Circuit Breaker Pattern - Zero-Downtime Degradation

The "Cascading Failure" Problem

Imagine this sequence:

User opens app on iOS Simulator
SharedPreferences.getInstance() throws MissingPluginException
Cache initialization fails
App bootstrap crashes. User sees a blank screen forever.

This is a cascading failure - one component's failure brings down the entire system.

Our Solution: Three-Tier Fallback Strategy

We implemented a Circuit Breaker Pattern with automatic driver fallback:

// lib/core/cache/data/datasources/cache_manager.dart
class CacheManager {
  Future<void> _initializeDrivers() async {
    // Tier 0: Memory (ALWAYS works - The Safety Net)
    _drivers[CacheDriverType.memory] = MemoryDriver();
    log('Memory driver initialized', name: 'Cache');

    // Tier 1: SharedPreferences (graceful failure)
    try {
      final prefs = await SharedPreferences.getInstance();
      _drivers[CacheDriverType.sharedPrefs] = SharedPrefsDriver(prefs);
      log('SharedPreferences driver available', name: 'Cache');
    } catch (e) {
      if (_config?.logFallbacks == true) {
        log('WARNING: Disk storage failed. Falling back to Memory.', name: 'Cache');
      }
      // App continues - memory driver is the fallback
    }

    // Tier 2: SecureStorage (optional, graceful failure)
    try {
      const storage = FlutterSecureStorage(
        iOptions: IOSOptions(
          accessibility: KeychainAccessibility.first_unlock_this_device,
        ),
      );
      _drivers[CacheDriverType.secureStorage] = SecureStorageDriver(storage);
      log('SecureStorage driver available', name: 'Cache');
    } catch (e) {
      if (_config?.logFallbacks == true) {
        log('SecureStorage unavailable: $e', name: 'Cache');
      }
    }
  }

  CacheDriver getDriver(String? driverName) {
    if (driverName != null) {
      final driverType = CacheDriverType.fromString(driverName);
      if (driverType != null && _drivers.containsKey(driverType)) {
        final driver = _drivers[driverType]!;
        if (driver.isAvailable) return driver;

        if (_config?.logFallbacks == true) {
          log('Driver $driverName unavailable, using fallback', name: 'Cache');
        }
      }
    }
    // Always fallback to memory (guaranteed to work)
    return _defaultDriver ?? _drivers[CacheDriverType.memory]!;
  }
}

Architectural Benefit:
This ensures that even if the underlying platform storage is completely broken (e.g., during a buggy OS update, CI environment, or iOS Simulator), the app remains functional using in-memory storage for the session.

Production Impact:

Before Circuit Breaker: 0.3% crash rate on app launch
After Circuit Breaker: 0% cache-related crashes in 8 months

How Circuit Breakers Work (The Mental Model)

In electrical systems, a circuit breaker "opens" when it detects a fault, preventing damage to the system. In software, the pattern is similar:

Key Difference from Traditional Exception Handling:

// ❌ Traditional approach (brittle)
try {
  final prefs = await SharedPreferences.getInstance();
  return prefs.getString('key');
} catch (e) {
  print('Error: $e');
  return null; // App loses data, user confused
}

// ✅ Circuit Breaker approach (resilient)
CacheDriver getDriver(String? driverName) {
  // Try requested driver
  if (driverName != null && _drivers[driverName].isAvailable) {
    return _drivers[driverName];
  }

  // Automatic fallback to memory
  return _drivers[CacheDriverType.memory]; // Always works
}

The circuit breaker automatically routes traffic to a working alternative, not just catching exceptions.

Part 4: Memory Management - The LRU Eviction Strategy

The Memory Leak We Didn't See Coming

Three months into production, our telemetry showed a disturbing pattern:

App Launch:    48MB memory
After 1 hour:  125MB memory  ← Creeping up
After 4 hours: 380MB memory  ← iOS memory warning
After 8 hours: CRASH         ← jetsam killed the app

This wasn't a leak in the traditional sense (no retain cycles). It was unbounded growth in the MemoryDriver:

class MemoryDriver extends CacheDriver {
  final Map<String, String> _cache = {};  // ← Grows forever

  @override
  Future<void> set(String key, String value) async {
    _cache[key] = value;  // ← No removal logic
  }
}

Understanding the Usage Pattern

When we analyzed the cache key distribution across user sessions:

Average user (90th percentile):
- Session length: 45 minutes
- Cache writes: 180 keys
- Memory impact: ~2MB
- Status: ✅ Acceptable

Power users (99th percentile):
- Session length: 8+ hours (overnight, left app open)
- Cache writes: 15,000+ keys
- Memory impact: 350MB+
- Status: ❌ App terminated by OS

The culprit? Our feature team was caching API responses aggressively:

// Every API response cached with a unique timestamp key
await cache.set(
  'api_response_${endpoint}_${timestamp}_${userId}',
  jsonEncode(response),
);

For a user who kept the app open all day, this created 14,000 unique keys (one every 30 seconds for feeds, notifications, etc.).

Why Standard Dart Collections Fail Here

You might think: "Just use a LinkedHashMap and limit the size."

final _cache = LinkedHashMap<String, String>();

void set(String key, String value) {
  if (_cache.length >= 1000) {
    _cache.remove(_cache.keys.first);  // ← Seems simple
  }
  _cache[key] = value;
}

Problem: This is FIFO (First-In-First-Out), not LRU (Least Recently Used).

If you write:

cache.set('user_config', configJson);  // Written at startup
// ... 1,000 other writes happen ...
cache.get('user_config');             // Still frequently accessed!

FIFO evicts 'user_config' after 1,000 writes, even if it's accessed every minute.

LRU keeps frequently accessed items and evicts the truly unused ones.

The LinkedHashMap LRU Pattern

Dart's LinkedHashMap maintains insertion order, which we exploit for LRU:

class MemoryDriver extends CacheDriver {
  final LinkedHashMap<String, String> _cache = LinkedHashMap();
  final int maxEntries;

  MemoryDriver({this.maxEntries = 1000});

  @override
  Future<void> set(String key, String value) async {
    // Step 1: Evict if at capacity (LRU policy)
    if (_cache.length >= maxEntries && !_cache.containsKey(key)) {
      final evictedKey = _cache.keys.first;  // Oldest entry
      _cache.remove(evictedKey);
      log('LRU EVICT: $evictedKey (size: ${_cache.length}/$maxEntries)', name: 'Cache');
    }

    // Step 2: Move to end (mark as recently used)
    _cache.remove(key);  // Remove from current position
    _cache[key] = value; // Re-insert at end

    log('Memory SET: $key (size: ${_cache.length}/$maxEntries)', name: 'Cache');
  }

  @override
  Future<String?> get(String key) async {
    final value = _cache.remove(key);  // Remove from current position

    if (value != null) {
      _cache[key] = value;  // Re-insert at end (mark as recently used)
      log('Memory HIT: $key (size: ${_cache.length}/$maxEntries)', name: 'Cache');
    } else {
      log('Memory MISS: $key', name: 'Cache');
    }

    return value;
  }
}

How This Works Internally

LinkedHashMap maintains two data structures simultaneously:

Data Structure:

When you do _cache.remove(key); _cache[key] = value;:

remove(key) unlinks the node from its current position in the linked list (O(1)) because the hash table provides direct node access
[key] = value inserts the node at the tail of the linked list (O(1))
keys.first always returns the head of the linked list—the least recently used entry (O(1))

This gives us O(1) reads, writes, and evictions—perfect for a cache.

The Algorithm in Action

Let's trace through a sequence of operations with maxEntries = 3:

// Initial state: Empty
cache.set('A', 'value_a'); // List: [A]
cache.set('B', 'value_b'); // List: [A, B]
cache.set('C', 'value_c'); // List: [A, B, C] ← Full

// Access 'A' (moves to end)
cache.get('A');            // List: [B, C, A]

// Add new item 'D' (evicts 'B' - least recently used)
cache.set('D', 'value_d'); // List: [C, A, D] (B evicted)

// Access 'C' (moves to end)
cache.get('C');            // List: [A, D, C]

// Add new item 'E' (evicts 'A')
cache.set('E', 'value_e'); // List: [D, C, E] (A evicted)

Key Insight: The most recently accessed items survive eviction, regardless of when they were originally added.

Production Impact: Before vs After

Before LRU (unbounded growth):

Device: iPhone 11 (4GB RAM)
Session: 6 hours (user fell asleep with app open)
Result: 
  - Memory: 420MB (98% of available)
  - Cache keys: 18,400
  - Outcome: App killed by jetsam
  - Crash rate: 0.3% of sessions

After LRU (1,000 entry limit):

Device: iPhone 11 (4GB RAM)
Session: 6 hours
Result:
  - Memory: 52MB (stable)
  - Cache keys: 1,000 (capped)
  - Cache hit rate: 94% (LRU kept the right data)
  - Outcome: App healthy
  - Crash rate: 0.0%

Architectural Insight: This is the same algorithm used in:

CPU L1/L2 caches (hardware)
Redis LRU eviction (databases)
CDN edge caches (Cloudflare, Fastly)

We're applying a decades-old systems algorithm to solve a mobile-specific problem.

Why 1,000 Entries?

We benchmarked different limits across device tiers:

Max Entries	Memory Usage (Avg)	Hit Rate	Evictions/Hour	Device Tier
100	5MB	78%	450	Low-end (<2GB RAM)
500	26MB	89%	120	Mid-range (2-4GB)
1,000	52MB	94%	45	High-end (>4GB)
5,000	260MB	96%	12	Tablets/iPads

The sweet spot: 1,000 entries gives us:

94% hit rate (users rarely notice cache misses)
52MB memory footprint (acceptable on modern devices)
45 evictions/hour (low churn, stable performance)

Part 7: The Strategy Pattern - Swappable Storage Backends

Early versions used magic strings for driver selection:

// ❌ BAD: Magic strings everywhere
await cache.set('key', 'value', driver: 'shared_prefs'); // Typo-prone

We replaced this with a type-safe Strategy Pattern:

// lib/core/cache/domain/strategies/cache_driver_strategy.dart
enum CacheDriverType {
  memory('memory'),
  sharedPrefs('shared_prefs'),
  secureStorage('secure_storage');

  const CacheDriverType(this.value);
  final String value;

  static CacheDriverType? fromString(String? value) {
    if (value == null) return null;

    try {
      return values.firstWhere((t) => t.value == value);
    } catch (e) {
      throw ArgumentError(
        'Invalid cache driver: "$value". Valid drivers are: ${values.map((t) => t.value).join(", ")}',
      );
    }
  }
}

// Abstract strategy interface
abstract class CacheDriver {
  CacheDriverType get type;
  String get name => type.value;
  bool get isAvailable;

  Future<void> set(String key, String value);
  Future<String?> get(String key);
  Future<bool> has(String key);
  Future<void> remove(String key);
  Future<void> clear();
  Future<List<String>> keys();
}

Why the Strategy Pattern Matters

The Strategy Pattern allows us to swap algorithms (storage backends) at runtime without changing client code.

Before (Tight Coupling):

// App code is tightly coupled to SharedPreferences
final prefs = await SharedPreferences.getInstance();
await prefs.setString('key', 'value');

// To switch to Hive, you'd need to find and replace every SharedPreferences call
final box = await Hive.openBox('cache');
await box.put('key', 'value');

After (Strategy Pattern):

// App code depends on interface, not implementation
await Cache.set('key', 'value', driver: 'shared_prefs');

// To switch to Hive, just implement CacheDriver interface
class HiveDriver extends CacheDriver {
  @override
  Future<void> set(String key, String value) async {
    final box = await Hive.openBox('cache');
    await box.put(key, value);
  }
  // ... rest of interface
}

// Register the new driver
_drivers[CacheDriverType.sharedPrefs] = HiveDriver();
// That's it! All existing code works with zero changes

The Three Concrete Strategies

1. MemoryDriver (In-Memory Strategy):

class MemoryDriver extends CacheDriver {
  final LinkedHashMap<String, String> _cache = LinkedHashMap();

  @override
  bool get isAvailable => true; // Always available

  @override
  Future<void> set(String key, String value) async {
    // LRU eviction logic (shown earlier)
  }
}

2. SharedPrefsDriver (Persistent Strategy):

class SharedPrefsDriver extends CacheDriver {
  final SharedPreferences _prefs;

  SharedPrefsDriver(this._prefs);

  @override
  bool get isAvailable => true; // Checked during initialization

  @override
  Future<void> set(String key, String value) async {
    await _prefs.setString(key, value);
  }
}

3. SecureStorageDriver (Encrypted Strategy):

class SecureStorageDriver extends CacheDriver {
  final FlutterSecureStorage _storage;

  SecureStorageDriver(this._storage);

  @override
  bool get isAvailable => true; // Checked during initialization

  @override
  Future<void> set(String key, String value) async {
    await _storage.write(key: key, value: value);
  }
}

Benefits:

Type Safety: Compile-time errors for invalid driver names
Swappable: Can replace SharedPreferences with Hive without changing UI code
Testable: Easy to inject mock drivers for testing
Discoverable: Enum lists all available drivers

Example - Swapping to Hive:

class HiveDriver extends CacheDriver {
  @override
  CacheDriverType get type => CacheDriverType.sharedPrefs;

  // Implement using Hive instead of SharedPreferences
  // UI code doesn't change at all!
}

Architectural Insight: The Strategy Pattern is one of the Gang of Four design patterns. It's used by:

Payment processors (Stripe, PayPal, Apple Pay - same interface, different implementations)
Compression libraries (gzip, brotli, zstd - same API, different algorithms)
Logging frameworks (console, file, network - same log() call, different outputs)

Part 10: Type-Safe Serialization - Generics Done Right

Flutter's SharedPreferences only stores primitives (String, int, bool, double). We needed to store complex objects.

The Challenge:

// ❌ This doesn't compile
await prefs.set('user', userObject); // SharedPreferences can't store objects

Our Solution: Automatic JSON Serialization

// lib/core/cache/data/datasources/cache_storage.dart
class CacheSerializer {
  static String serialize<T>(T value) {
    // Primitives
    if (value is String) return value;
    if (value is int) return value.toString();
    if (value is double) return value.toString();
    if (value is bool) return value.toString();

    // Collections
    if (value is Map || value is List) {
      return jsonEncode(value);
    }

    // Custom objects (convention: must have toJson())
    try {
      final json = (value as dynamic).toJson();
      return jsonEncode(json);
    } catch (e) {
      throw CacheSerializationException(
        type: T,
        value: value,
        message: 'Type $T must implement toJson() for serialization',
      );
    }
  }

  static T deserialize<T>(String raw) {
    // Primitives
    if (T == String) return raw as T;
    if (T == int) return int.parse(raw) as T;
    if (T == double) return double.parse(raw) as T;
    if (T == bool) return (raw == 'true') as T;

    // JSON types
    if (T == Map || T == List) {
      return jsonDecode(raw) as T;
    }

    // Generic JSON (when type is dynamic)
    try {
      return jsonDecode(raw) as T;
    } catch (e) {
      throw CacheSerializationException(
        type: T,
        message: 'Failed to deserialize type $T from: $raw',
        cause: e,
      );
    }
  }
}

This enables type-safe usage:

// Store complex objects
final user = User(name: 'Alice', age: 30);
await Cache.set<User>('current_user', user);

// Retrieve with type safety
final user = await Cache.get<User>('current_user'); // Returns User, not Map!

// Collections work too
await Cache.set<List<String>>('tags', ['flutter', 'dart']);
final tags = await Cache.get<List<String>>('tags'); // Returns List<String>

Why Generics Matter

Without Generics (Type Unsafe):

// ❌ Brittle: No compile-time safety
dynamic user = await cache.get('current_user');
print(user.name); // Runtime error if user is null or not User type

With Generics (Type Safe):

// ✅ Safe: Compiler enforces type
User? user = await cache.get<User>('current_user');
print(user?.name); // Compiler forces null check

The Convention: `toJson()` and `fromJson()`

For custom objects, we follow the json_serializable convention:

class User {
  final String name;
  final int age;

  User({required this.name, required this.age});

  // Serialization method (required for Cache.set)
  Map<String, dynamic> toJson() => {
    'name': name,
    'age': age,
  };

  // Deserialization factory (required for Cache.get)
  factory User.fromJson(Map<String, dynamic> json) => User(
    name: json['name'],
    age: json['age'],
  );
}

// Now this "just works"
await Cache.set<User>('user', user);
final retrieved = await Cache.get<User>('user');

Why this convention?

It's the standard used by json_serializable package
It's self-documenting (you know how to serialize by looking at the class)
It's testable (you can unit test toJson() and fromJson() independently)

Benefits:

Type Safety: Compile-time guarantees
Auto Serialization: No manual JSON encoding
Helpful Errors: Clear messages when serialization fails

// If you forget toJson(), you get a clear error:
class BadUser {
  final String name;
  // No toJson() method!
}

await Cache.set<BadUser>('user', badUser);
// Throws: CacheSerializationException: Type BadUser must implement toJson() for serialization

Part 12: Configuration as Code - Avoiding Magic Numbers

Avoid magic numbers scattered throughout code. We used a Value Object for configuration:

// lib/core/cache/domain/entities/cache_config.dart
class CacheConfig {
  /// Enable Time-To-Live functionality
  final bool enableTTL;

  /// Maximum key length for validation
  final int maxKeyLength;

  /// Log driver fallbacks for operational monitoring
  final bool logFallbacks;

  /// Maximum entries in memory cache (LRU limit)
  final int memoryMaxEntries;

  const CacheConfig({
    this.enableTTL = true,
    this.maxKeyLength = 250,
    this.logFallbacks = true,
    this.memoryMaxEntries = 1000,
  });

  /// Default production configuration
  factory CacheConfig.defaults() => const CacheConfig();

  /// For low-memory devices (< 2GB RAM)
  factory CacheConfig.forLowMemoryDevices() => const CacheConfig(
    memoryMaxEntries: 300,
    maxKeyLength: 100,
  );

  /// For high-end devices (> 6GB RAM)
  factory CacheConfig.forHighEndDevices() => const CacheConfig(
    memoryMaxEntries: 5000,
  );

  /// Development environment (verbose logging)
  factory CacheConfig.development() => const CacheConfig(
    logFallbacks: true,
  );

  /// Production environment (minimal logging)
  factory CacheConfig.production() => const CacheConfig(
    logFallbacks: false,
  );

  @override
  String toString() =>
      'CacheConfig(ttl: $enableTTL, maxKeyLength: $maxKeyLength, '
      'logFallbacks: $logFallbacks, memoryMaxEntries: $memoryMaxEntries)';
}

Why Configuration as Code?

Before (Magic Numbers):

// ❌ Scattered throughout codebase
if (_cache.length >= 1000) { // What's special about 1000?
  // evict
}

if (key.length > 250) { // Why 250?
  throw Exception('Key too long');
}

log('Fallback detected'); // Log in production? Development?

After (Configuration Object):

// ✅ Centralized, self-documenting
if (_cache.length >= config.memoryMaxEntries) {
  // evict (config explains the limit)
}

if (key.length > config.maxKeyLength) {
  throw CacheException('Key too long: max ${config.maxKeyLength}');
}

if (config.logFallbacks) {
  log('Fallback detected');
}

Usage with Dependency Injection:

// main_dev.dart (Development)
void main() async {
  await Cache.initialize(
    config: CacheConfig.development(),
  );
  runApp(MyApp());
}

// main_prod.dart (Production)
void main() async {
  await Cache.initialize(
    config: CacheConfig.production(),
  );
  runApp(MyApp());
}

Adaptive Configuration Based on Device

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Detect device capabilities
  final totalMemory = await getTotalMemory();
  final config = totalMemory < 2 * 1024 * 1024 * 1024
      ? CacheConfig.forLowMemoryDevices()
      : CacheConfig.defaults();

  await Cache.initialize(config: config);

  runApp(MyApp());
}

This allows the same codebase to run optimally on a $100 Android phone (300 cache entries) and a $1,000 iPhone (1,000 entries).

Benefits:

Type Safety: No string keys for config
Discoverability: IDE autocomplete shows all options
Environment-Specific: Different configs per environment
Testable: Easy to inject test configs

// In tests
testWidgets('Cache respects config limits', (tester) async {
  await Cache.initialize(
    config: CacheConfig(memoryMaxEntries: 10), // Small limit for testing
  );

  // Test LRU behavior with predictable limit
});

What's Next: The Security Layer

We've built a resilient cache that survives platform failures and memory constraints. Our system:

✅ Degrades gracefully via Circuit Breakers (0% crash rate)
✅ Prevents memory leaks with LRU Eviction (52MB vs 380MB)
✅ Provides type-safe serialization and clean interfaces
✅ Uses Strategy Pattern for swappable backends
✅ Configures behavior via code, not magic numbers

But there's a critical problem we haven't solved yet:

Your data is still stored in plain text.

When a security auditor showed us this on a rooted Android device:

adb shell
cat /data/data/com.yourapp/shared_prefs/FlutterSharedPreferences.xml

<string name="flutter.jwt_token">eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...</string>
<string name="flutter.api_key">sk_live_51HqK9...</string>

We got marked as a P0 Critical security issue.

Then the auditor used the extracted JWT token to authenticate API requests from Postman and access user
private data. Finding: Authentication tokens stored unencrypted.

In Part 2, we'll dive deep into:

🔐 iOS Keychain and Android KeyStore internals (hardware-backed encryption)
🔐 The 50-100x performance tax of secure storage (and when it's worth it)
🔐 Defense-in-depth strategies against root access, forensic tools, and malware
🔐 Security-aware exception design (handling Keychain failures gracefully)
🔐 Real-world attack scenarios and how to protect against them

The question isn't "Should I encrypt?" It's "What should I encrypt, and how?"

Because encrypting everything is too slow. Encrypting nothing is too risky. We need a strategy.

📖 Continue to Part 2: The JWT Token Incident - Why Your Flutter App's Cache Isn't Secure (And How to Fix It)

🐙 Star the repo: Flutter Production Architecture on GitHub

Tags: #Flutter #Cache #CircuitBreaker #LRU #CleanArchitecture #Mobile