Most mobile apps break under pressure. We learned this the hard way when our payment SDK crashed repeatedly during a flash sale, costing six figures in lost revenue. We built Jacaré, an open-source resilience framework that turned our brittle mobile clients into fault-tolerant systems, and today we're releasing the design blueprint. This article dissects the engineering behind Jacaré - named after the Portuguese word for alligator, a creature that survives extreme environments - and shows how we baked circuit breakers, offline-first sync, and adaptive retries directly into Android and iOS apps without sacrificing developer sanity.
If you've ever wrestled with socket timeouts, out-of-sync caches. Or cascading failures triggered by a single overloaded endpoint, you'll recognize the problems Jacaré solves. We spent two years hardening it in production across banking, ride-hailing. And IoT edge applications. Every claim here is backed by real telemetry from devices running on flaky 3G networks in rural São Paulo. Where the name jacaré first stuck during a debugging session near Pantanal wetlands,
The Genesis of Jacaré: Why Our Mobile Apps Kept Crashing at Scale
In early 2021, our team at Denver Mobile App Developer was responsible for a neobank's consumer app with 2. 3 million monthly active users, and the backend ran on Kubernetes, scaled horizontally,And passed all chaos engineering tests. The mobile client, however, treated every network call as an all-or-nothing operation. When the identity service experienced a 400ms latency spike during a push notification storm, a single unhandled SocketTimeoutException crashed the entire login flow for 31,000 users within 90 seconds. That incident lit the fire.
We instrumented the app with Firebase Crashlytics and found a pattern: 73% of critical crashes originated from unguarded network calls. And another 19% from unchecked local storage corruptions during background sync. Existing libraries like Retrofit offered interceptors. But developers had to write boilerplate for every endpoint. What we needed was a declarative resilience layer that could wrap any asynchronous operation - HTTP, gRPC, local database writes - and apply policies consistently. That kernel of an idea became jacaré.
Core Principles of the Jacaré Resilience Framework
Jacaré is built on four non-negotiable principles: Isolation, Graceful Degradation, Idempotency. And Adaptive Recovery. Every component, from the retry engine to the conflict resolver for offline queues, must satisfy these constraints. Isolation means that a failure in the notification module can't bring down the payment module. Graceful degradation translates 500s into stale-but-usable local data instead of blank screens. Idempotency guarantees that even if a write is retried three times due to network flickers, the server-side state changes exactly once. Adaptive recovery adjusts backoff windows based on real-time latency histograms, not static timers.
We formalized these principles into a small DSL that wraps Android's CoroutineScope and iOS's Task abstractions. A developer only needs to annotate a suspend function or an async throwing closure with @JacareResilient (or its Swift macro counterpart) and specify a policy: circuit breaker with 50% failure threshold over a rolling window of 10 requests, retry with exponential backoff capping at 30 seconds, or offline-safe with a TTL of 24 hours. Under the hood, Jacaré instruments everything with OpenTelemetry traces, making policy decisions auditable.
Implementing the Circuit Breaker Pattern with Jacaré on Android
The circuit breaker is the most misunderstood primitive in mobile engineering. We modeled Jacaré's circuit breaker after the classic three-state diagram (closed, open, half-open) from Michael Nygard's Release It! , but with mobile-specific additions: radio state awareness and battery level gating. In production, we found that a half-open state often led to user-visible retries when the user had already moved to another screen. Jacaré solves this by associating circuit breakers with lifecycle-aware scopes. If the user navigates away, the half-open probe is cancelled. And the circuit remains open until a fresh user-initiated request triggers a new probe.
Concretely, the Java/Kotlin implementation uses OkHttp's interceptor chain. A custom JacareCircuitBreakerInterceptor maintains a shared state holder backed by AtomicReference for thread safety. When the failure count exceeds the threshold within the window, it transitions to OPEN and immediately fails future calls with a CircuitOpenException - but still returns a cached Response if one exists. This cache is managed by a ResponseCachePolicy that respects Cache-Control headers and a secondary in-memory LRU with configurable staleness. The OkHttp interceptor API gave us the injection point we needed without forcing developers to change their networking layer.
Offline-First Data Synchronization: Jacaré's Conflict-Free Strategy
Many teams bolt offline support onto an online-first app. Which results in merge conflicts that silently drop user data. Jacaré takes the opposite approach: every write goes to a local SQLite (or Core Data) store first. And a background SyncEngine pushes mutations to the server when connectivity returns. The novelty is in how we handle conflicts. Instead of last-write-wins, Jacaré uses a lightweight implementation of Conflict-Free Replicated Data Types (CRDTs) based on the academic research on operation-based CRDTs
For structured data like user preferences or shopping cart items, every mutation is tagged with a monotonically increasing vector clock and a unique operation ID. The sync engine batches these into a changelog, which the server idempotently applies using a deterministic merge function. If the server already saw an operation (duplicate delivery), it acknowledges and skips. This design allowed our field-service app to operate flawlessly in underground metro stations and remote oil rigs. The message jacaré became synonymous with "it just works offline" among our beta testers.
Retry Policies and Exponential Backoff: Lessons from Jacaré in Production
Retries without backoff are a denial-of-service attack on your own backend. Our initial naive retry loop caused a thundering herd when a push notification campaign woke up 500,000 devices simultaneously, all retrying a temporarily slow endpoint every 2 seconds. The backend's thread pools saturated, and the full outage lasted 13 minutes. Jacaré replaced that with a decorrelated jitter backoff algorithm inspired by Polly, the. NET resilience library, which we ported to Kotlin.
The policy is defined as RetryPolicy(maxAttempts=3, medianBackoff=1. 0s, maxBackoff=30s, jitterFactor=0. 1). Crucially, Jacaré also tracks the server's Retry-After header; if the endpoint returns HTTP 429 or 503 with a backoff directive, Jacaré overrides the local policy and respects the server's guidance. This cooperative backpressure prevented our retail client from being rate-limited during checkout surges. Over six months, the error rate for transactional APIs dropped from 2, and 3% to 012%, as verified by our Prometheus histograms.
Integrating Jacaré with Existing Observability Stacks
Resilience policies are useless if you can't see them working. Jacaré automatically creates a span for every policy decision - circuit state changes, retry attempts, sync queue depths - and exports them via OpenTelemetry. We built a default exporter that pushes to any OTLP-compatible collector, but we also ship a first-class adapter for Firebase Performance Monitoring and DataDog. Since many mobile teams already have those instruments.
During a postmortem, we once traced a mysterious latency regression to a circuit breaker that kept flipping open because a new API version inadvertently returned 401 for expired tokens instead of 403, triggering the failure counter. Without Jacaré's spans, we would have spent hours digging through code. Now, any developer can query "show all circuits that opened in the last hour with reason" in Grafana. The telemetry also feeds a device-side health score that the app uses to dynamically switch between a lightweight "safe mode" and the full-featured UI - a powerful pattern we call adaptive UI resilience.
Jacaré Under the Hood: State Machines and Actor-Based Concurrency
Each Jacaré policy instance is implemented as an actor backed by a Kotlin Channel (or Swift's Actor in the iOS port). This design avoids locks entirely; internal state transitions occur serially within the actor's coroutine. For example, the circuit breaker actor holds a sealed class of states and processes commands like RecordSuccess, RecordFailure, Reset in order. The actor pattern proved especially valuable in Android, where multiple threads can call a shared repository concurrently without race conditions corrupting the failure count.
We also leveraged Android's WorkManager for long-lived background sync actors. WorkManager guarantees eventual execution even after process death. Which aligns with Jacaré's offline queue delivery semantics. The sync actor, upon receiving a batch of mutations, creates a periodic UniqueWork request tagged with JACARE_SYNC. If the device lacks connectivity, WorkManager defers the job until the network constraint is satisfied, automatically re
