DEV Community: Anietimfon Effiong

Clear the Lineup: Killing a Silent, Three-Cause Rendering Bug in a Flutter + Mapbox Noise Map

Anietimfon Effiong — Sat, 18 Jul 2026 16:02:56 +0000

This is a submission for DEV's Summer Bug Smash: Clear the Lineup powered by Sentry.

Project Overview

Ihanyi Elechi is a Flutter app that visualizes urban noise pollution as a live heatmap over real city maps. Sensor readings stream in from Firebase Firestore, get interpolated into a smooth noise surface using IDW (inverse distance weighting), and get painted onto a Mapbox map as a raster layer — similar to a weather radar overlay, but for decibels instead of rain. The contour surface is the app's core feature: without it, the app is just a list of unconnected data points on a map.

Bug Fix or Performance Improvement

The IDW noise contour layer would silently fail to render on some Android devices — no exception, no crash log, no error toast. It wasn't reproducible on my own test device, which made it especially hard to pin down. After ruling out malformed data (I validated every GeoJSON and PNG payload before it reached Mapbox — they were fine), I traced it to three separate, compounding root causes:

A coordinate type mismatch from an older Firestore ingestion path, where some latitude/longitude fields arrived as integers instead of doubles, silently corrupting the bounding-box math used to place the raster.
A Firestore query that depended on a composite index it didn't reliably have once a where filter was combined with an orderBy, causing thin or empty snapshots with zero client-side error.
A race condition on the Mapbox Android bridge: layer-building work runs in a background isolate, and if the user switched map styles during that window, layer calls would silently target a style object that no longer existed.

None of these alone reliably reproduced the bug — it only appeared when a specific overlap of bad data, thin query results, and a badly-timed style switch happened together.

Code

(Private repo — code changes included as snippets below. Happy to share a diff/screenshot on request.)

1. Style generation guard to stop mutating a torn-down Mapbox style:

int _styleGeneration = 0;

void onStyleLoaded() {
  _styleGeneration++;
  _isMapReady = true;
}

Future<void> _doLayerUpdate() async {
  if (!_isMapReady || _isUpdatingLayers || _mapboxMap == null) return;
  if (visibleReadings.isEmpty) return;

  _isUpdatingLayers = true;
  final gen = _styleGeneration;

  try {
    final results = await Future.wait([
      compute(buildGeoJsonFromReadings, rawList),
      compute(buildRasterBytes, rasterPayload),
    ]);

    if (_mapboxMap == null || _disposed || _styleGeneration != gen) return;
    await _cleanOldLayers();
    if (_mapboxMap == null || _disposed || _styleGeneration != gen) return;
    await _mapboxMap!.style.addSource(GeoJsonSource(id: 'noise-source', data: geoJson));
    if (_mapboxMap == null || _disposed || _styleGeneration != gen) return;
    // ...remaining layer calls, each gated the same way
  } finally {
    _isUpdatingLayers = false;
  }
}

2. Replacing an unreliable native bridge call with a standard image pipeline:

final dir = await getTemporaryDirectory();
final pngFile = File('${dir.path}/noise_raster.png');
await pngFile.writeAsBytes(rasterBytes, flush: true);
final pngUrl = Uri.file(pngFile.path).toString();

await _mapboxMap!.style.addSource(ImageSource(
  id: 'noise-raster-source',
  url: pngUrl,
  coordinates: [
    [bMinLng, bMaxLat],
    [bMaxLng, bMaxLat],
    [bMaxLng, bMinLat],
    [bMinLng, bMinLat],
  ],
));

3. Renderability guard against bad coordinate types + query simplified to avoid the composite index dependency:

bool _isRenderable(Noise n) =>
    n.latitude.abs() <= 90 && n.longitude.abs() <= 180 && n.noiseLevel > 0;

List<Noise> _parseSnapshot(QuerySnapshot snap) {
  return snap.docs
      .map((d) => Noise.fromMap({...d.data() as Map<String, dynamic>, 'id': d.id}))
      .whereType<Noise>()
      .where(_isRenderable)
      .toList();
}

_allDataSub = _db
    .collection('noise_readings')
    .orderBy('timestamp', descending: true)
    .limit(1200)
    .snapshots()
    .listen(_onAllData, onError: _onStreamError);

4. Fail-loud fallback instead of a silent empty result:

if (nearby.isEmpty) {
  final sorted = [...allReadings];
  sorted.sort((a, b) => _calculateDistanceKm(center.lat, center.lng, a.latitude, a.longitude)
      .compareTo(_calculateDistanceKm(center.lat, center.lng, b.latitude, b.longitude)));
  readings = sorted.take(120).toList();
  debugPrint('⚠️ No nearby readings. Using fallback nearest readings: ${readings.length}');
}

My Improvements

My approach was to stop assuming this was one bug. Once I confirmed the data payloads were valid at every stage, I had to accept the failure was happening between stages rather than in any single stage — which pointed toward timing and state, not data shape. That reframing was the actual unlock: I started asking "why would this pipeline abort with zero signal?" instead of "why is this raster malformed?"

The style-generation counter was the most interesting technical decision. A simple _mapboxMap != null check isn't enough when the object reference is still valid but represents a torn-down state — Flutter's async/await model means a style teardown can happen mid-pipeline, and every await boundary needs to independently verify it's still safe to proceed. I also chose to abandon updateStyleImageSourceImage entirely rather than patch around its inconsistency, since routing through a standard file-based ImageSource sidesteps an entire class of Android GPU driver quirks instead of chasing them one device at a time.

Fixing all three causes together — not just the most visible one — is what made the fix reliable across devices instead of just reducing the failure rate.

The Contours That Refused to Exist: A Three-Bug Pileup in a Flutter Noise Map

Anietimfon Effiong — Sat, 18 Jul 2026 10:36:50 +0000

The Contours That Refused to Exist: A Three-Bug Pileup in a Flutter Noise Map

The setup

I built Ihanyi Elechi, a Flutter app that visualizes urban noise pollution as a live heatmap over real city maps. Sensor readings stream in from Firestore, get interpolated into a smooth noise surface using IDW (inverse distance weighting), and get painted onto a Mapbox map as a raster layer — think weather radar, but for decibels instead of rain.

The core promise of the app is the contour surface. If it doesn't render, the app is just a list of dots on a map. So when it silently stopped appearing on certain devices and certain zoom levels, that was a five-alarm bug.

The symptom

On some Android devices — never consistently reproducible on my own test phone, which is the worst kind of bug — the noise contour layer simply wasn't there. No error toast, no crash log, no exception in flutter run. The heatmap markers loaded fine. The base map loaded fine. The contour surface just... didn't exist. Users would zoom in, zoom out, switch map styles, and the colored noise overlay would never appear.

Chasing the wrong things first

My first instinct was that this was a rendering bug — maybe the GeoJSON was malformed, or the raster bytes were corrupted. I spent a day logging payload sizes and validating the generated PNG bytes before the file even reached Mapbox. They were fine. The image was valid every time.

That ruled out the data itself. So the problem had to be somewhere in the pipeline between "data is ready" and "layer is on screen" — and that's where it got interesting, because it wasn't one bug. It was three, and they only failed together.

Root cause #1 — a coordinate type mismatch silently killing valid readings

Some historical documents in the noise_readings collection had latitude/longitude stored as Firestore integers (from an earlier ingestion script) instead of doubles. My renderability filter:

bool _isRenderable(Noise n) =>
    n.latitude.abs() <= 90 && n.longitude.abs() <= 180 && n.noiseLevel > 0;

looked harmless, but upstream, Noise.fromMap wasn't normalizing numeric types consistently. Depending on how a given document had been written, latitude could arrive as an int, and a stray type coercion elsewhere in the parsing chain meant a subset of readings got dropped or, worse, defaulted to 0.0. Zero readings clustered at (0,0) don't throw — they just quietly poison the bounding-box calculation used to place the raster image on the map.

Root cause #2 — a Firestore query that needed a composite index it didn't have

The live stream query orders by timestamp and limits to the most recent 1200 documents:

_allDataSub = _db
    .collection('noise_readings')
    .orderBy('timestamp', descending: true)
    .limit(1200)
    .snapshots()
    .listen(_onAllData, onError: _onStreamError);

On its own this doesn't need a composite index. But an earlier version of this query added a where clause on area for regional filtering, alongside the orderBy. Firestore needs a composite index for that combination, and without it the query doesn't throw a loud client-side error in release builds the way it does in debug — it just returns an empty or partial snapshot on some devices depending on cached index state. That meant allReadings was sometimes a near-empty list, which meant the bounding box for the raster was degenerate (a single point, or NaN-adjacent), so _doLayerUpdate would bail out silently:

if (!_isMapReady || _isUpdatingLayers || _mapboxMap == null) return;
if (visibleReadings.isEmpty) return;

No crash. No log. Just... nothing drawn.

Root cause #3 — a threading/style-generation race on the Mapbox Android bridge

This was the one that made the bug device- and timing-dependent rather than deterministic. Building the raster PNG happens off the main isolate:

final results = await Future.wait([
  compute(buildGeoJsonFromReadings, rawList),
  compute(buildRasterBytes, rasterPayload),
]);

That's good practice — you don't want IDW math and Gaussian blurring blocking the UI thread. But it means there's a real gap in time between "start building the layer" and "attach the layer to the map." On slower Android devices, if the user switched map styles or the style reloaded during that gap, Mapbox's Android bridge would either silently no-op the addSource/addLayer calls against a style object that no longer existed, or — worse — attach the new layer to a style that was already being torn down.

The fix was a style generation counter, checked before every mutating call:

int _styleGeneration = 0;

void onStyleLoaded() {
  _styleGeneration++;
  ...
}

Future<void> _doLayerUpdate() async {
  ...
  final gen = _styleGeneration;
  ...
  if (_mapboxMap == null || _disposed || _styleGeneration != gen) return;
  await _cleanOldLayers();
  if (_mapboxMap == null || _disposed || _styleGeneration != gen) return;
  await _mapboxMap!.style.addSource(GeoJsonSource(...));
  ...
}

Every single await point in the layer-building pipeline re-checks that the style generation hasn't changed underneath it. If it has, the whole update aborts cleanly instead of throwing on a stale native style handle.

I also stopped relying on updateStyleImageSourceImage for pushing the raster bytes to the map — it's unreliable across different Android GPU drivers — and switched to writing the PNG to a temp file and loading it via a file:// URL through a standard ImageSource, which uses Mapbox's normal image-loading pipeline instead of a bridge call known to misbehave:

final dir = await getTemporaryDirectory();
final pngFile = File('${dir.path}/noise_raster.png');
await pngFile.writeAsBytes(rasterBytes, flush: true);
final pngUrl = Uri.file(pngFile.path).toString();

await _mapboxMap!.style.addSource(ImageSource(
  id: 'noise-raster-source',
  url: pngUrl,
  coordinates: [[bMinLng, bMaxLat], [bMaxLng, bMaxLat], [bMaxLng, bMinLat], [bMinLng, bMinLat]],
));

Why it took three fixes, not one

None of these three bugs alone reliably reproduced the missing contours:

Bad coordinate types alone just shifted the bounding box a bit — annoying, but the raster still usually appeared somewhere.
The missing composite index alone meant fewer readings, but often still enough to draw something.
The style-generation race alone only mattered if a style switch happened at exactly the wrong moment.

Combined, they compounded: bad data made bounding boxes fragile, missing readings made the raster payload marginal, and a badly-timed style switch turned "marginal" into "nothing rendered, no error." That's why it looked unreproducible — it needed a specific overlap of data state and user timing.

The fallback that also had to change

While fixing this, I also hardened the "no readings near the camera" fallback, which had a similar silent-failure shape — it now explicitly logs and falls back to the nearest historical readings within a capped radius rather than returning an empty set and letting the layer pipeline bail silently:

if (nearby.isEmpty) {
  final sorted = [...allReadings];
  sorted.sort((a, b) => _calculateDistanceKm(center.lat, center.lng, a.latitude, a.longitude)
      .compareTo(_calculateDistanceKm(center.lat, center.lng, b.latitude, b.longitude)));
  readings = sorted.take(120).toList();
  debugPrint('⚠️ No nearby readings. Using fallback nearest readings: ${readings.length}');
}

Lessons

"No error thrown" is not the same as "nothing went wrong." Both the missing composite index and the stale-style race failed silently by design — Firestore and the Mapbox Android bridge both prefer no-ops over exceptions in these situations, which is exactly what made this bug so hard to trace.
Type discipline at the data layer matters more than it seems. A single inconsistently-typed field, written months earlier, was still causing failures downstream in a completely unrelated rendering pipeline.
Async pipelines need generation guards, not just null checks. Checking _mapboxMap != null isn't enough when the object is still valid but represents a torn-down state. The style generation counter was the piece that actually made the fix reliable across devices.

Three bugs, one symptom, and a debugging path that only made sense once I stopped treating "the raster is malformed" as the leading hypothesis and started asking why the pipeline would abort with zero signal.

Microservices Are Not a Starting Point. They Are a Destination.

Anietimfon Effiong — Wed, 24 Jun 2026 14:15:31 +0000

Microservices Are Not a Starting Point. They Are a Destination.

I am going to say something that might get me ratio'd on Tech Twitter.

Most startups do not need microservices. Not right now. Maybe not for years.

I say this as someone who built one anyway.

VerifiedCore — a virtual number verification platform I founded and engineered solo — runs on 14 Spring Boot 3 services. Auth, wallet, payments, notifications, delivery, analytics, eSIM, call plans, reseller, number management, and more. Kafka for async events. gRPC for synchronous calls between services. Separate MongoDB databases per service. An API gateway in front of everything.

It is a genuinely complex system. And if I were starting over today, I would not build it this way. Not yet.

We Learned the Wrong Lesson From Netflix

The microservices movement was popularised by Netflix, Amazon, and Google. The argument made sense for them: massive engineering organisations, thousands of engineers stepping on each other's code, services that need to scale independently to handle hundreds of millions of users.

What the industry did with that lesson was cargo-cult it.

Developers read the Netflix case study and started splitting their todo-list app into a task-service, a user-service, and a notification-service before they had a single paying customer. Teams of three engineers started debating service mesh configurations and distributed tracing tooling before they had shipped anything worth tracing.

The architecture that solved Netflix's problems at 200 million users became the default starting point for teams building for 200 users. That is not how engineering decisions are supposed to work.

The Tax Is Real and Nobody Advertises It

When you adopt microservices early, you do not just adopt the benefits. You adopt the full infrastructure bill upfront, before you have the scale to justify it.

In my case, that bill looked like this:

Every service needs its own Dockerfile, its own health check, its own database migration tooling, its own Kafka consumer group, its own Redis configuration, and its own Spring Security config. Miss one — as I did with the payment service — and an entire feature silently breaks in production. Not with an error you can easily trace. With a 401 on every webhook that a payment provider sends you, meaning no payment ever completes, and you only find it by manually exercising the live flow weeks later.

With 14 services, there are 14 surfaces where that kind of gap can hide.

Local development became its own full-time job. My development machine could not start all 14 services simultaneously without Docker Desktop running out of memory. I had a documented procedure for starting services one at a time, waiting for each to report healthy before starting the next. JVM startup on a constrained host took anywhere from 8 to 15 minutes per service. A single rebuild could take long enough to make coffee, come back, and find it had failed silently mid-build.

This is not a complaint. It is the real cost of the architecture. And at the stage I was at — a solo founder still discovering what the product needed to be — I was paying that cost with time I should have been spending on the product itself.

"But What About Scaling?"

This is the most common objection I hear when I make this argument, so let me address it directly.

Your startup is almost certainly not at the scale where microservices provide a meaningful scaling advantage. If you are, you will know it — because you will have real traffic data telling you which specific service is the bottleneck. You will not be guessing.

The argument "we might need to scale this part independently someday" is not an engineering decision. It is anxiety dressed up as architecture.

A well-structured modular monolith — one where domain boundaries are clear and enforced inside the codebase — can be extracted into services later, when you have evidence that a specific module needs independent scaling. Shopify ran on a Rails monolith for years while handling billions in transactions. Stack Overflow serves millions of developers on a monolith that most engineers would call embarrassingly simple. Simple systems are debuggable. Debuggable systems ship.

Extracting a service from a modular monolith is hard work. It is not insurmountable. Starting with 14 services before you understand your domain is harder — because you are locking in service boundaries before you know where the real seams are. I have refactored within a monolith. I have also renegotiated a gRPC contract across a service boundary. They are not the same category of effort.

When Microservices Are Actually the Right Answer

I want to be precise here, because this is not a binary argument.

Microservices make sense when team size creates real coordination friction. When you have enough engineers that deploying one module requires synchronising with three other teams, service independence pays for itself. This is Conway's Law in action — your system architecture will mirror your communication structure. If your communication structure is two people talking across a desk, your architecture should reflect that.

They make sense when you have measured a bottleneck that genuinely requires independent scaling. Not assumed one. Measured one.

They make sense when different parts of the system have such different operational profiles — uptime requirements, latency tolerances, deployment cadences — that a monolith's shared fate becomes an actual liability rather than a theoretical one.

None of those are circumstances that describe a startup in its first year. Maybe not in its second.

What I Would Tell Myself Before I Started

Build one service. Call it backend. Give it clean internal package structure — user, wallet, payment, notification — with strict rules about what can call what. Write it the same way you would write the microservices version, except everything runs in one process.

You will ship faster. You will find bugs faster. Your local development setup will be a single docker compose up. When you eventually outgrow it, you will know exactly where to make the first cut — because your traffic data and your team structure will tell you, instead of your imagination.

The goal of architecture is not to build the system that could theoretically handle your best-case future. It is to build the system that ships your product today while leaving the right doors open for tomorrow.

Microservices are a destination. A modular monolith is how you earn the right to need them.

I build backend infrastructure and mobile products. Currently working on VerifiedCore — a virtual number verification API for developers. If this resonated, I write more pieces like this alongside technical deep-dives on Java Spring Boot and Flutter.

How I Prevented Duplicate API Requests on Slow Mobile Networks in Flutter

Anietimfon Effiong — Wed, 24 Jun 2026 13:54:19 +0000

How I Prevented Duplicate API Requests on Slow Mobile Networks in Flutter

The Bug That Only Happens in the Field

Your app works perfectly in development.

Then a farmer in rural Nigeria opens it on a 2G connection. He fills in his farm details, taps Save, and nothing happens. So he taps again. And again.

Three requests reach your server. Three farm records get created. He has no idea why.

This is a weak network idempotency problem. The request went through. The response never came back. The app assumed failure.

A loading spinner and a disabled button won't save you here. The user closes the app, reopens it, and submits again. Or the OS kills the app mid-request. You need a smarter pattern.

This is how I solved it while building AgroXcel — a Flutter platform for Nigerian farmers managing farm data and boundaries on rural 2G/3G networks.

Why Not Just Disable the Submit Button?

Disabling a button only protects the current UI session.

It does not help when:

The app is killed mid-request by the OS
The user reopens the app and resubmits
The network drops after the request has already left the device
The server processes the request but the response never returns

Idempotency solves the problem at the request level, not the UI level. The button guard is still useful — but it is the last line of defence, not the first.

How the Pattern Works

User Taps "Save"
       ↓
Generate UUID (once — never regenerated on retry)
       ↓
Serialize payload → JSON string
       ↓
Store in Hive queue
       ↓
Send request + Idempotency-Key header
       ↓
        Success (2xx)?
       ┌──────┴──────┐
      Yes             No (network error)
       ↓                    ↓
Remove from queue    Increment retryCount in Hive
                     Retry on next reconnect
                     (max 5 attempts)

The server uses the key to deduplicate. Same key = same intent = process only once.

The Setup

# pubspec.yaml
dependencies:
  flutter_riverpod: ^2.5.1
  hive_flutter: ^1.1.0
  uuid: ^4.3.3
  dio: ^5.4.3
  internet_connection_checker: ^1.0.0+1  # connectivity_plus alone is not enough

dev_dependencies:
  hive_generator: ^2.0.1
  build_runner: ^2.4.9

Step 1: Model the Pending Operation in Hive

Store payload as a JSON string, not Map<String, dynamic>. Hive's generated TypeAdapters do not reliably handle nested maps at runtime — serializing to a string avoids that entirely.

import 'dart:convert';
import 'package:hive/hive.dart';

part 'pending_operation.g.dart';

@HiveType(typeId: 0)
class PendingOperation extends HiveObject {

  @HiveField(0)
  late String id;              // the idempotency key — generated once, never changed on retry

  @HiveField(1)
  late String endpoint;        // e.g. '/api/v1/farms'

  @HiveField(2)
  late String payloadJson;     // JSON string — NOT Map<String, dynamic> (Hive adapter limitation)

  @HiveField(3)
  late DateTime createdAt;

  @HiveField(4)
  late int retryCount;

  // Convenience getter so callers don't have to decode manually
  Map<String, dynamic> get payload => jsonDecode(payloadJson) as Map<String, dynamic>;
}

Run flutter pub run build_runner build to generate the adapter.

Step 2: The Offline Queue Service

class OfflineQueueService {
  static const _boxName = 'pending_ops';

  Future<Box<PendingOperation>> get _box async =>
      await Hive.openBox<PendingOperation>(_boxName);

  // Call this BEFORE making any network request.
  Future<PendingOperation> enqueue(
    String endpoint,
    Map<String, dynamic> payload,
  ) async {
    final op = PendingOperation()
      ..id = const Uuid().v4()           // one UUID per user intent — never recreated
      ..endpoint = endpoint
      ..payloadJson = jsonEncode(payload) // serialize to string for Hive compatibility
      ..createdAt = DateTime.now()
      ..retryCount = 0;

    final box = await _box;
    await box.put(op.id, op);            // key by idempotency key for direct lookup
    return op;
  }

  Future<void> dequeue(String operationId) async {
    final box = await _box;
    await box.delete(operationId);
  }

  Future<List<PendingOperation>> getPending() async {
    final box = await _box;
    return box.values.toList();
  }
}

Step 3: The Repository — Two Separate Methods for New vs Retry

This is the most important design decision in the whole pattern.

Do not call saveFarm() when retrying. That generates a new UUID and breaks the idempotency guarantee entirely. Use a dedicated retryOperation() method that reuses the original key.

class FarmRepository {
  final Dio _dio;
  final OfflineQueueService _queue;

  FarmRepository(this._dio, this._queue);

  // Called on first submission — generates the UUID and enqueues.
  Future<void> saveFarm(Map<String, dynamic> farmData) async {
    final op = await _queue.enqueue('/api/v1/farms', farmData);
    await _sendOperation(op);
  }

  // Called by the retry sweep — reuses the ORIGINAL UUID. Never generates a new one.
  Future<void> retryOperation(PendingOperation op) async {
    await _sendOperation(op);
  }

  Future<void> _sendOperation(PendingOperation op) async {
    try {
      await _dio.post(
        op.endpoint,
        data: op.payload,
        options: Options(headers: {
          // Same key on every attempt — server deduplicates on this value.
          'Idempotency-Key': op.id,
        }),
      );

      // Dio throws on non-2xx by default, so reaching this line means
      // the server returned 200, 201, 202, or 204 — any successful 2xx.
      await _queue.dequeue(op.id);

    } on DioException catch (e) {
      if (e.response != null) {
        // Got a real HTTP error (4xx/5xx) — not a network issue.
        // Remove from queue: retrying a bad request won't help.
        await _queue.dequeue(op.id);
        rethrow;
      }

      // Network failure — leave in Hive and increment the retry counter.
      op.retryCount++;
      await op.save();
    }
  }
}

Step 4: The Riverpod Provider

final farmRepositoryProvider = Provider((ref) => FarmRepository(
  ref.read(dioProvider),
  ref.read(offlineQueueServiceProvider),
));

final saveFarmProvider =
    StateNotifierProvider<SaveFarmNotifier, AsyncValue<void>>(
  (ref) => SaveFarmNotifier(ref.read(farmRepositoryProvider)),
);

class SaveFarmNotifier extends StateNotifier<AsyncValue<void>> {
  final FarmRepository _repo;

  SaveFarmNotifier(this._repo) : super(const AsyncData(null));

  Future<void> save(Map<String, dynamic> farmData) async {
    // Guard against double-taps within the same session.
    if (state is AsyncLoading) return;

    state = const AsyncLoading();
    state = await AsyncValue.guard(() => _repo.saveFarm(farmData));
  }
}

In the UI:

ElevatedButton(
  onPressed: state is AsyncLoading
      ? null
      : () => ref.read(saveFarmProvider.notifier).save(farmData),
  child: state is AsyncLoading
      ? const CircularProgressIndicator()
      : const Text('Save Farm'),
)

Step 5: Retry on Reconnection — With a Real Internet Check and a Cap

connectivity_plus and Connectivity() tell you whether the device is connected to a network — WiFi, mobile data, ethernet. They do not tell you whether the internet is actually reachable. A device on WiFi with no uplink passes the connectivity check and still fails the request.

Use internet_connection_checker for a real probe:

class ConnectivityRetryService {
  final OfflineQueueService _queue;
  final FarmRepository _repo;

  ConnectivityRetryService(this._queue, this._repo);

  void listen() {
    Connectivity().onConnectivityChanged.listen((result) async {
      if (result == ConnectivityResult.none) return;

      // Connectivity ≠ internet. Probe a real host before retrying.
      final hasInternet = await InternetConnectionChecker().hasConnection;
      if (!hasInternet) return;

      final pending = await _queue.getPending();

      for (final op in pending) {
        // Hard cap — after 5 failures, surface an error instead of retrying forever.
        if (op.retryCount >= 5) {
          // TODO: emit a notification or a Riverpod state so the UI can prompt the user.
          continue;
        }

        // Use retryOperation — NOT saveFarm — to preserve the original UUID.
        await _repo.retryOperation(op);
      }
    });
  }
}

What the Server Needs to Do

Store the idempotency key and return the existing result on duplicate:

// Spring Boot — same concept applies in NestJS
@PostMapping("/api/v1/farms")
public ResponseEntity<?> createFarm(
    @RequestHeader("Idempotency-Key") String idempotencyKey,
    @RequestBody FarmRequest request
) {
    // Return the already-created record instead of inserting a duplicate.
    if (farmRepo.existsByIdempotencyKey(idempotencyKey)) {
        return ResponseEntity.ok(farmRepo.findByIdempotencyKey(idempotencyKey));
    }
    return ResponseEntity.status(201).body(farmService.create(request, idempotencyKey));
}

Add a UNIQUE index on idempotency_key in your migration. The database is your last line of defence if the application-level check ever races.

In production, expire idempotency keys after a reasonable retention window (24–72 hours is common) to prevent unbounded table growth. A nightly cleanup job or a TTL-based index on created_at handles this cleanly.

Results

After implementing this pattern in AgroXcel:

Duplicate submissions were eliminated during testing on unstable 2G/3G networks
Failed submissions could be recovered automatically after reconnection without user action
Users no longer needed to re-enter data after temporary network failures

The Hive queue also gave us a side benefit: farm data is never silently lost mid-submission, even if the user gets a call, switches apps, or the OS kills the process.

Quick Checklist

[ ] Generate the idempotency key once per user intent — not per retry
[ ] Store payload as a JSON string in Hive — not Map<String, dynamic>
[ ] Write to Hive before the network call, never after
[ ] Separate saveFarm() (new key) from retryOperation() (reuse key)
[ ] Dequeue on any 2xx response — Dio throws on anything else by default
[ ] Use InternetConnectionChecker in the retry sweep, not just Connectivity
[ ] Implement a retry cap (5 attempts) and surface failures to the user when hit
[ ] The server stores the key with a UNIQUE constraint and returns the existing result on duplicate

Built while developing AgroXcel — a Flutter platform for Nigerian farmers managing farm boundaries and records on rural 2G/3G networks.

Hello DEV — I'm Anietimfon, a Full-Stack Engineer from Lagos

Anietimfon Effiong — Wed, 24 Jun 2026 13:26:38 +0000

Hey DEV community 👋

My name is Anietimfon Effiong, a full-stack software engineer based in Lagos, Nigeria.

A slightly unusual background

My degree is in Chemical Engineering — not Computer Science. I graduated from the University of Uyo in 2024 with a 3.9 GPA while teaching myself software engineering on the side.

I've been writing production code since 2022. The degree and the career ended up being two completely separate things, and I have zero regrets about that.

What I build

I work mostly in the backend and mobile space:

Java Spring Boot 3 — microservices, gRPC, Kafka, PostgreSQL
Flutter — cross-platform mobile apps for Android and iOS
NestJS / TypeScript — when the project calls for it

I've shipped products in fintech, logistics, VPN infrastructure, and agricultural tech.

What I'm working on right now

I'm building VerifiedCore — a virtual number verification platform for developers. Think: rent a real phone number, receive an OTP, verify your account. Backed by a 14-service Java microservices architecture, a Flutter mobile app, and SDKs published to npm, PyPI, and Packagist.

I'm also deep into AWS ML Engineering (SageMaker, MLOps) via Udacity — slowly adding machine learning to my toolkit.

Why I'm here

To share what I build and what I learn — the real stuff, including the bugs that nearly broke production.

My first article is already up:
👉 Preventing Double-Spend in Spring Boot 3 Using Pessimistic SERIALIZABLE Locking

That one came directly from a live bug I found while building VerifiedCore's wallet service. Three concurrent webhooks. One wallet. Things got interesting.

If you're building in Java, Flutter, or fintech — say hi. Always happy to connect.

Preventing Double-Spend in Spring Boot 3 Using Pessimistic SERIALIZABLE Locking

Anietimfon Effiong — Wed, 24 Jun 2026 12:56:14 +0000

Preventing Double-Spend in Spring Boot 3 Using Pessimistic SERIALIZABLE Locking

The Problem Nobody Warns You About

You build a fintech feature. It works perfectly in testing.

Then you go live.

A payment provider like OPay or Stripe retries its webhook — because networks are unreliable and they want to guarantee delivery. Now you have three copies of the same webhook hitting your service at the same millisecond.

Your wallet gets credited three times. Your user is now rich. Your company is not.

This is double-spend. And it's not a rare edge case — it's guaranteed to happen in production.

Why This Is Harder Than It Looks

The obvious fix is to check before you credit:

// DANGEROUS — don't do this
if (!alreadyCredited(referenceId)) {
    walletService.credit(userId, amount);
}

The check and the credit are two separate operations. Between them, another thread can pass the same check. Both threads credit the wallet. You've gained nothing.

This is a check-then-act race condition, and a standard @Transactional annotation on its own will not save you.

By default, Spring uses READ_COMMITTED isolation. Threads can still read the same "not yet credited" state from each other before either one commits. You need to go further.

What Actually Happened in VerifiedCore

Building VerifiedCore — a virtual number verification platform on Spring Boot 3 + PostgreSQL — I hit this exact bug during live testing.

I fired three concurrent webhook deliveries at the same payment reference:

The wallet correctly credited exactly once — the locking worked ✅
But the payment_transactions row ended up showing FAILED ❌

Why? A slower concurrent attempt's failure-path write committed after the successful attempt's write. The last writer won, and it wrote the wrong status.

Two separate races. Two different fixes.

Fix 1: Lock the Wallet Row with Pessimistic SERIALIZABLE

The wallet-service needed to guarantee that only one credit attempt per referenceId could succeed, no matter how many concurrent requests came in.

Step 1 — Add a locking query to your repository

public interface WalletRepository extends JpaRepository<Wallet, UUID> {

    // SELECT ... FOR UPDATE — acquires an exclusive row-level lock.
    // Every other transaction trying to read this row will BLOCK until we commit.
    @Lock(LockModeType.PESSIMISTIC_WRITE)
    @Query("SELECT w FROM Wallet w WHERE w.userId = :userId")
    Optional<Wallet> findByUserIdForUpdate(@Param("userId") UUID userId);
}

Step 2 — Run the credit inside a SERIALIZABLE transaction

@Service
public class WalletService {

    @Transactional(isolation = Isolation.SERIALIZABLE)
    public CreditResult credit(UUID userId, BigDecimal amount, String referenceId) {

        // Safe to check here — PESSIMISTIC_WRITE locks the row before this read.
        // No other transaction can slip in between the check and the credit.
        if (walletTransactionRepo.existsByReferenceId(referenceId)) {
            return CreditResult.ALREADY_CREDITED;
        }

        Wallet wallet = walletRepo
            .findByUserIdForUpdate(userId)  // acquires the exclusive lock
            .orElseThrow();

        wallet.setBalanceUsd(wallet.getBalanceUsd().add(amount));
        walletRepo.save(wallet);

        // Record the referenceId so future concurrent attempts bail out above.
        walletTransactionRepo.save(
            WalletTransaction.builder()
                .walletId(wallet.getId())
                .amountUsd(amount)
                .referenceId(referenceId)
                .build()
        );

        return CreditResult.SUCCESS;
    }
}

What this buys you:

PESSIMISTIC_WRITE → database issues SELECT ... FOR UPDATE on the wallet row
Thread 1 acquires the lock. Threads 2 and 3 block — they don't race, they wait
When thread 1 commits, threads 2 and 3 wake up, see existsByReferenceId = true, and return ALREADY_CREDITED
SERIALIZABLE isolation also blocks phantom reads — where a row inserted by another transaction is invisible to your current snapshot, letting a second thread pass the same existence check

Live test result with three concurrent webhooks:

Thread 1 → CREDIT_SUCCESS    (wallet: $0.00 → $57.50)
Thread 2 → ALREADY_CREDITED  (no-op)
Thread 3 → ALREADY_CREDITED  (no-op)

Exactly what you want.

Fix 2: Stop the Last Writer from Corrupting the Payment Row

The wallet was safe. But the payment_transactions status row wasn't.

Thread 1 wrote status = COMPLETED. Thread 3's failure path wrote status = FAILED 200ms later — after thread 1 had already committed. Last writer wins. Wrong status persists.

The fix is optimistic locking on the payment entity. One annotation:

@Entity
@Table(name = "payment_transactions")
public class PaymentTransaction {

    @Id
    private UUID id;

    private String status;

    // Hibernate increments this on every UPDATE.
    // If two threads try to update the same row version, the slower one
    // throws ObjectOptimisticLockingFailureException instead of silently
    // overwriting the winner's result.
    @Version
    private Long version;

    // ... other fields
}

That's it. Hibernate now generates:

UPDATE payment_transactions
SET status = 'FAILED', version = 2
WHERE id = ? AND version = 1  -- rejected if version already moved past 1

If thread 1 committed version 1 → 2 (writing COMPLETED), thread 3's update targets version = 1 — which no longer exists. PostgreSQL rejects it. No silent overwrite.

One important rule: don't try to catch and recover inside the same @Transactional method. Once Hibernate throws an optimistic lock failure, the persistence context is in an unusable state. Let it propagate to your controller:

@PostMapping("/webhooks/payment/opay")
public ResponseEntity<?> handleWebhook(@RequestBody String payload) {
    try {
        paymentService.processConfirmedPayment(reference);
        return ResponseEntity.ok().build();
    } catch (ObjectOptimisticLockingFailureException e) {
        // The row was already updated by a faster concurrent request.
        // The important guarantee (no overwrite) is already met.
        // Return 200 so the provider doesn't retry and compound the problem.
        log.warn("Stale concurrent webhook for {}: ignoring", reference);
        return ResponseEntity.ok().build();
    }
}

The Two-Layer Pattern

These two mechanisms solve different races:

Layer	Mechanism	Protects
Wallet balance	`PESSIMISTIC_WRITE` + `SERIALIZABLE`	No duplicate credit to the ledger
Payment status	`@Version` (optimistic lock)	No stale FAILED overwrite on the transaction row

Pessimistic locking blocks threads upfront. Use it where you can't tolerate any concurrent modification — wallet balances, escrow holds, inventory.
Optimistic locking lets threads race and rejects the loser at commit time. Use it where conflicts are rare — status fields, audit rows, idempotency metadata.

One More Gotcha: Truncate Your Error Messages

When the serialization error fired in VerifiedCore, PaymentService tried to store the raw JDBC exception text into a varchar(500) column.

The exception text was longer than 500 characters. The insert crashed. The transaction row got stuck in PENDING forever — not even FAILED.

Always truncate before storing:

private static String truncate(String s, int max) {
    // Postgres throws DataException if you exceed column length.
    // Truncate here so the row always persists, even on ugly errors.
    return (s != null && s.length() > max)
        ? s.substring(0, max - 3) + "..."
        : s;
}

Ship the feature. Then ship the error handling.

Pre-Ship Checklist

[ ] Every wallet credit checks referenceId inside the locked transaction — not before acquiring the lock
[ ] Your @Transactional isolation is SERIALIZABLE on the write path, not the Spring default READ_COMMITTED
[ ] Your payment entity has a @Version column backed by a real DB column (bigint NOT NULL DEFAULT 0)
[ ] Your webhook controller catches ObjectOptimisticLockingFailureException and returns 200 — not 500
[ ] Your referenceId column has a UNIQUE index — the database is your last line of defense
[ ] Your error-reason columns are long enough, or you're truncating before save

Built and battle-tested while developing VerifiedCore — a virtual number verification platform for developers.