Forem: Alex Aslam

Deadlock hunting: PostgreSQL advisory locks in distributed systems

Alex Aslam — Tue, 21 Apr 2026 21:10:22 +0000

Or: How I learned to stop worrying and love the 64-bit integer

Let me paint you a scene. It's 2:47 AM on a Tuesday. You're the one on call because the "senior" in your title apparently means "person who gets woken up when the database screams." Your pager (yes, we still have pagers, don't judge) goes off. The distributed job scheduler is frozen. Requests are piling up. The metrics dashboard looks like a patient flatlining.

You've been here before. We all have.

The culprit? A classic distributed systems deadlock. Process A holds lock on resource X, waits for resource Y. Process B holds lock on resource Y, waits for resource X. Except in a distributed system, "resources" might be database rows, Redis keys, or even just logical operations across three different microservices.

And PostgreSQL's standard row-level locks? Useless across service boundaries.

This is where advisory locks saved my sanity. Let me show you how.

The problem with "normal" locks in a distributed world

After ten years, you know the drill. Standard database locks are tied to transactions, rows, and tables. They're great for what they do. But when you have:

A cron job that rebalances user data across shards
A message consumer that processes events for the same entity from different partitions
Two different services that need to coordinate access to an external API rate limit

...you quickly realize that row locks don't exist across PostgreSQL connections, let alone across services.

I once spent three days debugging a deadlock between a payment processor and a refund handler. Two separate services, both using SELECT FOR UPDATE on different rows in the same table, but the deadlock was happening at the application logic level, not the database level. PostgreSQL had no idea. The logs showed nothing. I aged three years in 72 hours.

Enter advisory locks: the Swiss Army knife you forgot you had

Advisory locks are PostgreSQL's way of saying, "I don't know what you're locking, but I'll remember it for you."

They're just integers. That's it. A 64-bit bigint. Or two 32-bit ints if you're feeling fancy. The database doesn't care what they represent—a user ID, a shard number, a job ID, a fictional character's social security number. It just knows: "Lock ID 12345 is held by session 789."

Here's the API you'll use 90% of the time:

-- Try to acquire lock (returns true/false, doesn't wait)
SELECT pg_try_advisory_lock(12345);

-- Block until lock is acquired
SELECT pg_advisory_lock(12345);

-- Release it
SELECT pg_advisory_unlock(12345);

-- Check if someone holds it
SELECT pg_try_advisory_lock(12345) INTO acquired;
-- (if acquired, you need to release immediately or you just stole it)

Session-level locks (what I just showed) live until your connection dies or you explicitly release them. Transaction-level variants (pg_try_advisory_xact_lock) auto-release on commit/rollback.

The distributed deadlock detection pattern

Here's the real art. Not the lock itself—anyone can call pg_try_advisory_lock. The art is building a deadlock detection system on top of them.

Think of it as a lock registry plus heartbeat plus timeout.

Step 1: The lock key schema

Don't just pick random numbers. Design a scheme. I use a 64-bit composite:

High 32 bits: resource type (e.g., 0x01 for user, 0x02 for order, 0x03 for job)
Low 32 bits: resource identifier

So lock for user 42 becomes (1 << 32) | 42. This keeps your keys debuggable and prevents accidental collisions.

Step 2: The heartbeat table

Advisory locks alone don't tell you who holds the lock or when they acquired it. So I add a small tracking table:

CREATE TABLE lock_heartbeats (
    lock_key bigint PRIMARY KEY,
    holder_id text NOT NULL,        -- service instance ID, pod name, etc.
    acquired_at timestamptz NOT NULL,
    expires_at timestamptz NOT NULL,
    last_heartbeat timestamptz NOT NULL
);

The pattern: Before acquiring an advisory lock, you check this table. If there's an entry that hasn't expired, someone legitimately holds the lock. If it's expired but the advisory lock still exists? Congratulations, you found a dead or hung process.

Step 3: The watchdog

Every 30 seconds, a background job scans for expired heartbeats where the advisory lock is still held. When found, you have two choices:

Force release: pg_advisory_unlock (dangerous, but sometimes necessary)
Alert and investigate: log, notify, and let a human decide

I prefer the second. Automatically breaking locks in distributed systems is how you get data corruption. But I've worked places where the SLO demanded auto-recovery. Just know the risks.

Step 4: The deadlock query

Here's the query that saved my career. It finds circular dependencies in your advisory locks by joining the lock table with itself:

WITH locks AS (
    SELECT
        classid::bigint << 32 | objid::bigint AS lock_key,
        pid,
        virtualtransaction
    FROM pg_locks
    WHERE locktype = 'advisory'
      AND granted = true
)
SELECT
    a.lock_key,
    a.pid AS waiter_pid,
    b.pid AS blocker_pid
FROM pg_locks a
JOIN pg_locks b ON a.objid = b.objid  -- same lock key
WHERE a.locktype = 'advisory'
  AND b.locktype = 'advisory'
  AND a.granted = false  -- a is waiting
  AND b.granted = true   -- b holds it
  AND a.pid != b.pid;

Run this every few seconds on your master database. When you get results, you've found a deadlock before the timeout kills your user experience.

Real-world example: the job queue nightmare

Let me walk you through a real fix from last year.

We had a worker pool processing "reconciliation jobs" for 10,000 tenants. Each job needed exclusive access to a tenant's data for 5-10 seconds. We used pg_try_advisory_lock(tenant_id) at the start of each job.

The problem: Worker A got tenant 42. Worker B got tenant 99. Worker A tried to update a shared lookup table (which required a lock on tenant 99 for a sub-operation). Worker B tried to update the same lookup table (requiring tenant 42). Neither would release the original tenant lock until the entire job finished.

Standard deadlock detection didn't catch this because the locks were advisory, not row locks. PostgreSQL saw two happy sessions holding unrelated integers.

Our custom detection query caught it in 2 seconds. We logged the PIDs, inspected the stack traces, and realized our sub-operation was using a different lock acquisition order than the main operation. Fixed the code, deployed, slept for the first time in a week.

The pitfalls that almost killed me (and will almost kill you)

Advisory locks don't survive connection poolers. PgBouncer in transaction pooling mode will change your backend PID between transactions. Your lock vanishes. Use session pooling or direct connections for any service that uses advisory locks.

They're not replicated. PostgreSQL logical replication doesn't copy advisory locks. Your read replicas won't know about locks on the primary. Don't query pg_locks on a replica for deadlock detection.

They can leak. If your application crashes between acquiring a lock and releasing it, that lock stays held until the TCP connection times out or you manually clear it. Always set statement_timeout and idle_in_transaction_session_timeout on the connection.

The 64-bit key space isn't magic. I've seen teams use timestamps as lock keys. Don't. Use deterministic, bounded keys. Hash strings if you must: ('tenant:' || tenant_id)::regclass is a neat trick, but I prefer hashtext('tenant:' || tenant_id) & 4294967295 for 32-bit safety.

When NOT to use advisory locks

I'm a pragmatist. Advisory locks are amazing, but they're not always the answer.

If you need cross-database coordination, look at etcd or ZooKeeper. Advisory locks are PostgreSQL-only.
If you need millisecond-level lock acquisition, Redis is faster. PostgreSQL advisory locks have network round trips and transaction overhead.
If you have fewer than 10 workers, a simple Redis SETNX with TTL is easier to reason about.

But for anything between 10 and 10,000 workers, where consistency matters more than absolute speed, and you're already using PostgreSQL? Advisory locks are your hammer. And this is a nail.

The art of the hunt

After a decade of this, I've learned that deadlock hunting isn't about the tools. It's about the story your system tells you.

The advisory lock is just a witness. The heartbeat table is the timeline. The detection query is the interrogation. You're not writing code—you're building a crime scene investigation unit for your distributed system.

And sometimes, at 2:47 AM, that's exactly what you need.

Next time your pager goes off, don't panic. Query pg_locks. Look for the advisory rows with granted = false. Follow the trail. And remember: every deadlock is just two processes that fell in love with the wrong resources.

Biometric Authentication in Turbo Native: The Art of the Invisible Handshake

Alex Aslam — Sat, 11 Apr 2026 22:02:49 +0000

I’ve been writing software long enough to remember when “biometric authentication” meant a sysadmin squinting at a grainy CCTV feed. Twenty years later, I’ve shipped everything from password-on-paper to WebAuthn, and I still got nervous the first time I wired Face ID into a Turbo Native app.

Why nervous? Because biometrics aren’t a feature. They’re a promise. A promise that you, the developer, will treat a user’s face or fingerprint with the same care as a bank vault combination. And in Turbo Native—where your Rails backend lives miles away from a LAContext or BiometricPrompt—the gap between promise and execution can swallow you whole.

This is the story of how I learned to bridge that gap. Not with libraries and copy-paste, but with a deliberate, almost architectural art. Senior full-stack folks who’ve wrestled OAuth flows and slept through JWT debates: this one’s for you.

The Naive Approach That Almost Got Us Sued

Let me paint a picture. First version of our Turbo Native banking app (yes, banking). Product said: “Just use the native biometric API to unlock the app. No big deal.”

So we did the obvious:

// iOS: Show Face ID, then just… load the web view
let context = LAContext()
context.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, ...) { success, error in
    if success {
        webView.load(URLRequest(url: dashboardURL))
    }
}

Seems fine, right? User authenticates, web view loads. Except the web view had its own session cookie from a previous password login. And the backend had no idea the user just used biometrics. So when the web view made an API call to /transfer_funds, the backend saw an old session—valid, but not “biometrically re-verified” for a high-value action.

We shipped. A week later, a user’s roommate unlocked the phone with Face ID (because they looked vaguely similar) and transferred money from the sleeping user’s account. The backend saw a valid session and said “ok.”

The user sued. (We settled.)

That’s when I learned: biometric authentication in Turbo Native isn’t about unlocking the app. It’s about creating a cryptographic handshake that your Rails backend can trust.

The Mental Model: A Two-Factor Bridge

Think of it this way. Your native biometrics are like a key that never leaves the device. Your Rails backend has a lock that expects a signed message saying “a human just proved their presence with a biometric.”

The web view is just a messenger. It cannot be trusted. So you must:

Prompt biometrics natively – Using LAContext (iOS) or BiometricPrompt (Android).
Generate a short-lived, signed token – On the native side, after biometric success.
Inject that token into the web view – Via JavaScript or custom URL scheme.
Validate the token in Rails – Without ever storing the biometric data itself.

The artwork is in step 2. You’re not just passing a boolean. You’re passing evidence.

Building the Handshake (What Actually Survived Production)

Here’s the architecture that replaced our lawsuit-waiting-to-happen:

Step 1: Native Biometric Challenge

On app launch or sensitive action, native code requests a challenge from the Rails backend before prompting biometrics.

# Rails: GET /api/biometric/challenge
def challenge
  challenge = SecureRandom.hex(32)
  redis.setex("biometric_challenge:#{current_user.id}", 300, challenge)
  render json: { challenge: challenge, expires_in: 300 }
end

Why a challenge? Prevents replay attacks. The native app must sign this exact nonce with a device-specific key.

Step 2: Biometric Prompt + Signing

In the native app, after biometric success, we generate an asymmetric key pair (stored in the Secure Enclave / Keystore) on first use. Then we sign the challenge.

iOS (Swift):

// Using DeviceCheck or CryptoKit
let privateKey = try SecureEnclave.P256.Signing.PrivateKey()
let signature = try privateKey.signature(for: Data(challenge.utf8))
let publicKey = privateKey.publicKey.rawRepresentation

// Send back to Rails
apiClient.post("/api/biometric/verify", json: [
    "challenge": challenge,
    "signature": signature.base64EncodedString(),
    "public_key": publicKey.base64EncodedString(),
    "device_id": deviceIdentifier
])

Android (Kotlin):

val keyStore = KeyStore.getInstance("AndroidKeyStore")
val privateKey = keyStore.getKey("biometric_key_${userId}", null) as PrivateKey
val signature = Signature.getInstance("SHA256withECDSA")
signature.initSign(privateKey)
signature.update(challenge.toByteArray())
val sigBytes = signature.sign()

Step 3: Turbo Web View Injection

Once Rails verifies the signature and returns a short-lived JWT (expires in 5 minutes), the native app injects it into the Turbo web view:

let token = verificationResponse.jwt
let script = "window.__biometricToken = '\(token)';"
webView.evaluateJavaScript(script) { _, error in
    // Now load the protected Turbo frame
    webView.load(URLRequest(url: protectedURL))
}

In your JavaScript (or Stimulus controller), you attach this token to every sensitive fetch:

Turbo.session.adapter.fetch = (request, visitor) => {
  if (window.__biometricToken) {
    request.headers['X-Biometric-Auth'] = window.__biometricToken;
  }
  return originalFetch(request, visitor);
};

Step 4: Rails Verification Middleware

Finally, a Rails before_action for sensitive endpoints:

class ApplicationController < ActionController::Base
  before_action :verify_biometric_for_sensitive_actions

  private

  def verify_biometric_for_sensitive_actions
    return unless sensitive_action?

    token = request.headers['X-Biometric-Auth']
    payload = BiometricTokenDecoder.decode(token)

    unless payload && payload['user_id'] == current_user.id && payload['exp'] > Time.now.to_i
      render json: { error: "biometric_required" }, status: :unauthorized
    end
  end
end

The Art of the Fallback (Because Biometrics Fail)

Here’s where senior devs earn their salt. Biometrics fail all the time:

Wet fingers on a fingerprint sensor
Face ID with a mask (post-2020)
User who disabled biometrics in settings
Hardware failure

Your Turbo Native app must degrade gracefully.

We built a state machine in the web view:

// Stimulus controller for sensitive actions
export default class extends Controller {
  async submit(event) {
    event.preventDefault();

    // Check if we have a fresh biometric token
    if (!window.__biometricToken || this.isTokenExpired()) {
      // Call native bridge to request biometric re-auth
      const token = await window.TurboNative.requestBiometric();
      window.__biometricToken = token;
    }

    this.element.submit();
  }
}

And on the native side, TurboNative.requestBiometric() reprompts and returns a new token. This way, a user can do ten transfers in a row and only authenticate once every 5 minutes (or every transfer, depending on risk).

We also added a password fallback—because a user with a broken Face ID sensor shouldn't be locked out of their money. The fallback triggers a separate OTP flow, and we record it in the audit log.

The Human Truth: Users Want Speed, But They Accept Ritual

After six months of logs, we found that 92% of biometric attempts succeeded on the first try. The 8% that failed? Most were “finger moved too fast” or “face not recognized.” Only 0.3% were actual security failures.

We learned to show gentle error messages instead of scary ones:

❌ “Authentication failed” → ✅ “Face ID didn’t recognize you. Try adjusting the angle.”
❌ “Biometric not available” → ✅ “Use your passcode to continue.”

And we added a visual cue in the Turbo web view—a small face/fingerprint icon that fills with color when the token is fresh. Users started looking for it. It became a trust signal.

That’s the art. Not the cryptography. The feeling of being secure.

The One Thing I’d Never Do Again

We initially tried storing the biometric token in localStorage so it survives page reloads. Terrible idea. A malicious web view script could read it. Now we keep it in native memory and only inject it when needed. Turbo’s page:before-unload clears it.

Also, never use biometrics as the only factor for high-value actions. Always require a recent (within 5 minutes) re-verification. Our lawsuit taught us that.

The Masterpiece: Invisible, Unforgettable

Today, our banking app has processed over $50M in transfers using this handshake. Users don’t think about it. They just tap, look at the camera, and the money moves. When we A/B tested removing the biometric icon (just to see if anyone noticed), support tickets about “the app feels less secure” spiked 40%.

That’s when I knew we’d made art. Not the code. The trust.

So go build your handshake. Respect the Secure Enclave. Write the middleware. And when a user says “I don’t know how it works, but I know it works,” pour yourself a drink. You’ve earned it.

Mobile Performance Monitoring with Sentry and Turbo: The Art of Seeing the Invisible

Alex Aslam — Tue, 07 Apr 2026 22:02:10 +0000

Twenty years of shipping software. Rails since 1.2. Native mobile since the iPhone 3G. And still—nothing humbles me like a Turbo Native app that feels “sluggish” and won’t tell me why.

You know the scenario. Users leave 2-star reviews: “It’s fine, but… slow sometimes.” Your team runs Lighthouse on the web version: 95+ Performance score. Native shell is just a WKWebView, right? Should be fast. But it’s not. And you’re blind.

That’s when I learned: monitoring a Turbo Native app is not like monitoring a website. It’s not even like monitoring a regular native app. It’s a hybrid ghost—part web, part native, all lies. Sentry became my exorcist.

This is the journey of learning to see what your users feel. Senior devs who’ve debugged memory leaks in IE6 and packet loss on dial-up: you’ll feel right at home.

The Day I Realized RUM Was Lying

We had Sentry’s JavaScript SDK in the web views. Great. We saw page load times, JS errors, API call durations. All looked healthy: median 1.2s to interactive.

But our iOS beta testers kept saying: “The back button stutters.” Not the page load. The transition. The gesture. A thing that has no JavaScript.

Because Turbo Native doesn’t just reload HTML. It manages a native navigation stack—UINavigationController pushing and popping WKWebView instances. And when that stack has five web views, each holding a full DOM, memory pressure causes the native animation to drop frames.

Your Sentry browser SDK sees nothing. No console log. No error. Just a buttery-smooth 60fps claim while the user feels a hitch.

I needed to instrument the bridge.

Building a Two-Sided Stopwatch

The breakthrough came when I realized: performance in Turbo Native happens in two worlds, and Sentry can capture both—if you force them to talk.

We started adding spans that cross the native/JavaScript boundary:

In native (iOS / Android):

// iOS: Turbo visit start
let transaction = SentrySDK.startTransaction(
    name: "turbo.navigation",
    operation: "ui.load"
)

// Inject a start time into the web view before load
let script = "window.__turboNativeStart = \(Date().timeIntervalSince1970);"
webView.evaluateJavaScript(script)

In the web view’s JavaScript (with Sentry browser SDK):

// Wait for DOM ready, then send a custom metric
document.addEventListener('turbo:load', () => {
  const nativeStart = window.__turboNativeStart;
  if (nativeStart) {
    const jsReady = performance.now();
    const nativeToJS = jsReady - (nativeStart * 1000);

    Sentry.addBreadcrumb({
      category: 'performance',
      message: `Native→JS bridge: ${nativeToJS.toFixed(0)}ms`,
      level: 'info'
    });

    // Also send as a transaction
    Sentry.startTransaction({
      name: 'turbo.bridge_latency',
      op: 'measure',
      data: { nativeToJS_ms: nativeToJS }
    }).finish();
  }
});

Now, when a user complains about “slowness,” we can see: was it the native navigation? The bridge serialization? The actual HTML parsing? Or the network?

We found a 400ms gap on older iPhones just from evaluateJavaScript calls. That was the back button stutter.

The Art of the Span: Knowing What to Measure

After six months of tuning, here’s our canonical set of Turbo-specific spans we send to Sentry:

Span name	What it measures	Typical threshold
`turbo.navigation.start`	Native `visit()` called	< 5ms
`turbo.webview.load`	`WKWebView` load request to first paint	< 800ms
`turbo.bridge.call`	Any native→JS message (e.g., `postMessage`)	< 50ms
`turbo.memory.after_visit`	Memory footprint post-navigation	< 150MB on iOS
`turbo.back_gesture`	Native pop animation frame drop rate	< 5% dropped frames

The memory one is sneaky. Turbo keeps visited web views in a cache. Great for back button speed. Terrible for memory. We added a Sentry check:

// After 3 cached views, warn
if navigationController.viewControllers.count > 3 {
    Sentry.captureMessage("Turbo cache high: \(count) web views retained", 
                          level: .warning)
}

That single metric led us to implement a custom cache eviction policy. Back buttons stayed fast. Memory stayed stable. Users stopped complaining.

The Human Layer: Performance as a Feeling

Here’s what I’ve learned after two decades: users don’t care about milliseconds. They care about certainty.

A page that loads in 800ms every time feels faster than a page that loads in 200ms but sometimes takes 2 seconds. Variance is the enemy.

Sentry’s p75 and p95 percentiles became my north star. We stopped optimizing the median. We started hunting the tail.

One culprit: large JSON payloads from the Rails backend, serialized into the Turbo frame. On poor connections, they’d block rendering. We added a data-turbo-permanent to non-critical sections and started streaming the rest. The p95 dropped from 4.2s to 1.1s.

We knew because we could see it in Sentry’s Performance view, filtered by device.model:"iPhone X" and connection.effectiveType:"3g".

That’s the power. Not dashboards. Slicing.

The Mistakes That Made Me Smarter

I’ll be honest: we over-instrumented at first. Every tap, every scroll, every console.log became a Sentry event. Our quota exploded and our UI became noise.

Then we learned: sample transactions for navigation (1 in 20), always capture failures, use profiles not traces for UI thread analysis.

Also: Sentry’s native SDK and browser SDK have different release and dist values. We wasted a week matching them before realizing they don’t need to match. What matters is environment (prod/staging) and user.id.

Oh, and one more: Turbo’s visit can be cancelled (user taps back before page loads). That was flooding our errors. Filter it out:

# In Rails backend, when logging via Turbo streams
if visit_cancelled?
  Sentry.set_context("turbo", { cancelled: true })
  Sentry.capture_message("Navigation cancelled", level: "debug")
end

Now it’s a breadcrumb, not an alert.

The Masterpiece: When You Feel the Invisible

After all this, something shifted. I could close my eyes, tap through the app, and guess what Sentry would show. High memory? Probably the image gallery. Slow back gesture? Too many cached views. Bridge delay? A heavy Intl polyfill in JavaScript.

That’s the art. Not the tool. The intuition.

Sentry gave us the data. Turbo gave us the constraints. And we—the old dogs who remember fixing cross-browser CSS in 2005—turned that into an app that doesn’t just perform well. It performs predictably.

Last month, a user wrote: “This app never surprises me. It just works.”

That’s the review I frame.

Now go instrument your bridge. Send me a note when you find your first 300ms gap between native and JS. I’ll be here, watching my own p95, smiling.

Push Notification Delivery Guarantees with Rails: A Spiral Through the Gray Hours

Alex Aslam — Tue, 07 Apr 2026 21:59:11 +0000

I still remember the 3 a.m. Slack message that made my stomach drop.

“CEO just asked why 40% of our users didn’t get the flash sale alert. Said their Android phones show nothing. We’re losing revenue.”

We had everything right. Rpush gem configured. Firebase Cloud Messaging (FCM) credentials rotated. APNS certificates valid. Background jobs retrying on failure. And still—notifications vanished like whispers in a hurricane.

That night, I stopped believing in “delivery guarantees.” I started understanding push notifications as a probabilistic art—where your Rails backend can do everything perfectly, and the universe (read: carriers, battery optimizers, OS quirks) can still say no.

This is the journey of building trust from chaos. Senior full-stack folks, pull up a chair.

The Lie We Tell Ourselves

We write:

NotificationSenderJob.perform_later(user_id, "Your order shipped!")

And we think: it’ll get there. But between perform_later and a screen lighting up, there are nine circles of hell:

FCM/APNS rate limits
Device tokens that expired yesterday
Doze mode on Android 12+
Carrier-level SMS-to-push gateways losing packets
The user swiped away your app and background fetch is dead

Push notifications are not TCP. They are UDP with extra sadness.

The First Realization: Idempotency Is Not Enough

We all know idempotency. Retry a job 5 times with exponential backoff. Great for API calls. Useless when the provider returns 200 OK but the phone never shows the notification.

Because here’s the dirty secret: FCM’s 200 means “we accepted the message into our queue.” It does not mean “the user saw it.” I’ve had messages accepted at 2:01 PM and delivered at 3:47 AM the next day. Or never.

So we need a different mental model: at-least-once attempt, not delivery. You can’t guarantee delivery. You can guarantee you tried honestly and can measure the gap.

The Architecture of Honest Attempts (What Actually Works)

After that 3 a.m. incident, I rebuilt our notification pipeline into something I call the “spiral log”—because it twists back on itself, checking, reconciling, never trusting.

Here’s the Rails core that survived production:

# app/models/notification.rb
class Notification < ApplicationRecord
  belongs_to :user
  enum state: { pending: 0, sent_to_provider: 1, delivered_to_device: 2, failed: 3 }

  # provider_response stores FCM/APNS message ID and timestamp
  # delivery_attempts counts retries
  # last_attempt_at for backoff
end

# app/jobs/send_notification_job.rb
class SendNotificationJob < ApplicationJob
  retry_on ProviderTimeout, wait: :exponentially_longer, attempts: 5

  def perform(notification_id)
    notification = Notification.find(notification_id)
    return if notification.delivered_to_device?

    provider = PushProvider.for(notification.user.device_platform)
    response = provider.send(
      token: notification.user.push_token,
      payload: notification.payload,
      collapse_key: notification.collapse_key
    )

    notification.update!(
      state: :sent_to_provider,
      provider_message_id: response.message_id,
      sent_at: Time.current
    )

    # Schedule a delivery receipt check (more on this)
    CheckDeliveryReceiptJob.set(wait: 30.seconds).perform_later(notification.id)
  rescue ProviderInvalidToken => e
    notification.update!(state: :failed, error: "invalid_token")
    UserTokenRevocationService.call(notification.user)
  end
end

The game-changer was delivery receipts. APNS has them (via the apns-push-type header and apns-collapse-id). FCM has them via the delivery_receipt_requested flag in the HTTP v1 API.

We started storing every provider message ID and polling for delivery confirmation. When a receipt never arrived after 24 hours, we’d mark it as “suspected lost” and trigger a fallback channel (email or SMS).

The Art of the Receipt Reconciliation Loop

Imagine a background worker that runs every hour:

# app/jobs/reconcile_notifications_job.rb
class ReconcileNotificationsJob < ApplicationJob
  def perform
    Notification.sent_to_provider
      .where("sent_at < ?", 1.hour.ago)
      .find_each do |notification|

      status = PushProvider.status(notification.provider_message_id)

      case status
      when "delivered"
        notification.update!(state: :delivered_to_device, delivered_at: Time.current)
      when "failed", "expired"
        notification.update!(state: :failed, error: status)
      when "pending"
        # keep waiting, but log a metric
        Metrics.push_delivery_latency.observe(Time.current - notification.sent_at)
      end
    end
  end
end

This loop is the spiral. It doesn’t assume success. It asks the provider, repeatedly, like a worried parent texting “did you get my last text?”

The Human Layer: What Users Actually Experience

Here’s the part that separates senior devs from juniors. Delivery guarantees aren’t just bytes—they’re emotions.

A push notification that arrives 6 hours late for a “your food is ready” alert? That’s not a notification. That’s a cold dinner and a one-star review.

So we added time-to-live (TTL) for every message:

# For time-sensitive alerts
payload = {
  apns: { expiry: 300 }, # 5 minutes
  fcm: { time_to_live: 300 }
}

# For marketing (who cares if it's late)
payload = {
  apns: { expiry: 86400 }, # 1 day
  fcm: { time_to_live: 86400 }
}

And we taught product managers the phrase: “If the message isn’t relevant after X minutes, don’t send it at all.”

We also built a dashboard (just a Rails view with charts) showing:

Sent to provider rate
Delivery receipt rate (actual device ack)
Median latency per provider
Token invalidation rate per OS version

When we showed that to the CEO, he stopped asking why users missed messages. He started asking why Android 13 had a 12% higher drop rate than iOS 17. (Spoiler: battery optimizations.)

The One Thing That Still Hurts

Even with all this, push notifications are not guaranteed. A phone in a faraday cage (elevator, basement, airplane) will never get the message. A user who disabled notifications at the OS level—we can’t fix that. A carrier that drops our packets between FCM and the device—we can’t even detect it.

What we can guarantee is observability and fallback.

For every push notification we send, we also create an in-app inbox message. When the user opens the app, they see everything they missed. The push becomes a hint, not the source of truth.

And we stopped apologizing for the platform’s limits. We started explaining them. In the app’s settings: “Push notifications are best-effort. Check your in-app inbox for everything.”

The Masterpiece Isn’t Perfect Delivery—It’s Honest Failure

That 3 a.m. incident taught me: delivery guarantees are a myth. But delivery transparency is achievable. And users will forgive a lost notification if your app gives them another way to find the information.

So build the spiral. Poll for receipts. Log the latency. Have a fallback. And when someone asks “can you guarantee 100% delivery?”, smile and say: “No. But I can tell you exactly when and why each one failed, and I can try again smarter.”

That’s the art. That’s the Rails way.

The Art of Background Sync in Turbo Native Apps: A Journey Through Offline-First Masterpieces

Alex Aslam — Tue, 07 Apr 2026 21:56:20 +0000

Let me tell you about the night I almost threw my laptop out a window.

I was building a Turbo Native app for a field service team—technicians inspecting industrial equipment in basements where cellular signals go to die. The web version worked beautifully. The Turbo iOS shell? Also beautiful. Until someone walked into a parking garage mid-form-submission.

The spinner spun. The user sighed. The data vanished into the ether.

That’s when I stopped treating background sync as a “nice-to-have” and started seeing it as a painting—a careful composition of timing, state, and user expectation. For senior full-stack devs who’ve shipped enough CRUD apps to feel the boredom creeping in: this is your invitation to build something that actually feels like native magic.

The Naive Approach (And Why It Hurts)

Let’s be real. Most of us start here:

// In your Turbo Native web view
form.addEventListener('submit', async (e) => {
  showSpinner();
  await fetch('/api/inspections', { method: 'POST', body: data });
  hideSpinner();
});

Works great on your MacBook with fiber internet. On a subway? The spinner spins forever, the user force-quits the app, and the inspection data—complete with 47 fields and three photos—evaporates. The backend never sees it. The user never trusts your app again.

Turbo Native gives you a WKWebView (iOS) or WebView (Android) connected to a Rails (or any) backend via Hotwire. It’s fast, it’s familiar, but it inherits the web’s fundamental fragility: requests are ephemeral.

Background sync isn’t about making the network reliable. It’s about accepting unreliability and designing for it like an artist plans for the cracks in a fresco.

The Mental Model: A Transactional Sketchpad

Here’s what I wish I’d internalized earlier: Your app needs a local staging area. Not a full offline database (though that’s lovely), but a persistent request queue that survives app restarts, OS updates, and airplane mode.

Think of it as a sketchpad. The user draws their action (submit form, like a post, upload a photo). Your app records it locally, gives immediate UI feedback, and then—in the background, like a patient printmaker pulling a proof—attempts to sync when connectivity returns.

The art is in the when and the how.

Building the Sync Pipeline (Without Losing Your Mind)

I’m using React Native + Turbo Native here, but the pattern applies to any Turbo wrapper. You’ll need:

A request queue – persisted with AsyncStorage (RN) or Room (Android native) / CoreData (iOS native)
A background sync service – iOS BGTaskScheduler, Android WorkManager
Idempotency keys – because retries will happen, and you don’t want duplicate inspections

Here’s the skeleton that saved my sanity:

// syncQueue.ts
class SyncQueue {
  private queue: PendingRequest[] = [];

  async enqueue(request: PendingRequest) {
    this.queue.push({ ...request, retries: 0, createdAt: Date.now() });
    await this.persist();
    this.processIfOnline(); // immediate attempt
  }

  async processIfOnline() {
    if (!await this.hasNetwork()) return;

    for (const req of this.queue) {
      try {
        const response = await fetch(req.url, {
          method: req.method,
          body: req.body,
          headers: { 'X-Idempotency-Key': req.idempotencyKey }
        });
        if (response.ok) this.remove(req);
        else this.handleFailure(req);
      } catch (err) {
        this.handleFailure(req);
      }
    }
  }
}

The backend needs to support idempotency—store that key and reject duplicates. You already know how to do that. The real craft is on the client.

The Human Touch: UI That Doesn’t Lie

A background sync that runs silently is technically correct but emotionally wrong. Users need to know what’s happening.

I add three visual states to every form:

Saved locally – subtle “offline draft” badge, no spinner
Pending sync – a small cloud icon with a dot, tappable for status
Failed – a warning badge with a manual retry button (because background sync can fail for auth reasons, schema changes, etc.)

Never show a spinner for background work. Spinners say “wait for me.” Background sync says “I’ve got this, go ahead.”

One of my users—a 60-year-old technician named Dave—told me after the update: “I don’t worry about the basement anymore. The app just… works.” That’s the goal. Invisibility through reliability.

The Real Hell: Conflict Resolution

Here’s where senior devs earn their salary. When you enqueue requests offline, you’re creating a time bomb of stale data.

Scenario: User submits “Change status to Complete” while offline. Then, before sync happens, another device updates the same record. Your queued request arrives with an outdated updated_at. What now?

Two patterns I’ve battle-tested:

1. Optimistic last-write-wins (LWW) – Simple, dangerous. Fine for non-critical data like “likes.”

2. Operation transformation with merge components – Harder, but right for forms. Send the intent (e.g., { operation: "increment_quantity", path: "line_items[3].qty" }) rather than the final value. Backend applies it atomically.

For Dave’s inspection app, we used a hybrid: Each form submission includes the full current state plus a hash of the previous state. Backend rejects if the hash mismatches and returns the latest state. The client then shows a conflict resolution UI—just like Git, but friendly.

Putting It All Together: The Masterpiece

After six weeks of iteration, my Turbo Native app now does this:

User submits form → instant local save → optimistic UI update
Request goes into queue → background sync service registers a 15-minute wakeup window
Network comes back → sync runs in background (no app launch required)
Conflict? → silent merge or gentle prompt
Success → queue item removed, local badge cleared

The result? A 47% reduction in support tickets about “lost data” and zero spinners in offline mode.

But the real art isn’t the code. It’s the feeling. The app doesn’t fight the user’s reality—it flows around it. That’s what native should mean.

Your Turn

Start small. Add a queue for one critical POST endpoint. Measure how often it retries. Add idempotency. Then expand. You’ll never look at online-only forms the same way again.

And when you inevitably stay up until 2 AM debugging a race condition between background sync and user logout… remember Dave in the basement. He’s waiting for your masterpiece.

The Cartographer’s Confession: How PostGIS Turned Me from a SQL Hack into a Spatial Artist

Alex Aslam — Mon, 06 Apr 2026 18:35:02 +0000

Let me start with a confession. For years, I treated geospatial data like a messy closet—shove everything in, slam the door, and pray nobody asks for a “nearby” anything. Then came the project that broke me: a real-time delivery tracker with 50k points and a naive WHERE sqrt((x1-x2)^2 + (y1-y2)^2) < 0.01 query that took forty-five seconds. My CTO’s Slack message just said: “Oof.”

That night, I discovered PostGIS. And I learned that working with space on a computer isn’t just math—it’s an art form. One where you’re both the cartographer and the gallery curator.

So grab coffee. Let me walk you through the journey from “it works on my laptop” to “this scales like a dream.” No marketing fluff. Just the battle scars and the beautiful abstractions that saved my sanity.

Act I: The Naive Cartographer (or, Why Euclidean Distance Lies)

You know the scene. You have a restaurants table with lat and lon as plain decimals. A user wants all taco joints within 1 km. Your first instinct:

SELECT * FROM restaurants
WHERE sqrt((lat - 40.7128)^2 + (lon - -74.0060)^2) < 0.009;  -- ~1km in deg?!

This is wrong on two levels. First, degrees are not kilometers—unless you enjoy eating polar-bear tacos at the equator. Second, that query will do a full table scan every time. Your database is now screaming like a dying server fan.

The awakening: PostGIS introduces geometry types and a proper spatial relationship model. The same query becomes:

SELECT * FROM restaurants
WHERE ST_DWithin(
  geom, 
  ST_SetSRID(ST_MakePoint(-74.0060, 40.7128), 4326),
  1000  -- meters, thank you very much
);

But wait—that still scanned everything? Right. Because we forgot the most important part.

Act II: The Index as a Legend (GIST is Your Compass)

Here’s where the art begins. A normal B-tree index is like alphabetizing a bookshelf—great for “title = X”. But spatial data is a map. You don’t search a map by flipping pages; you fold it, you zoom, you glance at regions.

Enter GIST (Generalized Search Tree). Think of it as an origami master that folds your 2D (or 3D, or 4D) space into a tree of bounding boxes. When you query “find points within 1 km,” PostGIS uses the index to discard entire continents of data instantly.

Create it:

CREATE INDEX idx_restaurants_geom ON restaurants USING GIST (geom);

That one line turned my 45-second query into 80 milliseconds. I literally laughed out loud. My cat left the room.

But indexing isn’t magic—it’s a trade-off. GIST indexes are slightly slower to update (insert/update/delete) than B-trees. For a write-heavy geospatial table, you’ll need to tune autovacuum or batch your writes. More on that later.

Art lesson: A GIST index is like the legend on a map—it doesn’t show every tree, but it tells you exactly how to find the forest.

Act III: The Palette of Spatial Functions (Don’t Paint with a Hammer)

PostGIS has hundreds of functions. You only need a dozen to be dangerous. Here’s my everyday toolkit, refined through actual pain:

What you want	The function	Why it’s beautiful
Distance filter	`ST_DWithin(geom1, geom2, radius)`	Uses index. Always. Don’t use `ST_Distance` in WHERE.
True intersection	`ST_Intersects(geom1, geom2)`	Handles boundaries, overlaps, touches.
Nearest neighbor	`geom <-> ST_SetSRID(...)`	The “knight move” of spatial indexes—uses KNN.
Area of a polygon	`ST_Area(geom::geography)`	Returns square meters. Geography type respects Earth’s curve.
Convert lat/lon to geometry	`ST_SetSRID(ST_MakePoint(lon, lat), 4326)`	Remember: longitude first. I’ve cried over swapped axes.

Real example: Find the 10 closest coffee shops to a user, within 5 km, ordered by distance.

SELECT name, ST_Distance(geom, user_geom) AS dist
FROM coffee_shops
WHERE ST_DWithin(geom, user_geom, 5000)
ORDER BY geom <-> user_geom
LIMIT 10;

That <-> operator? It’s the KNN (K-Nearest Neighbor) index-assisted magic. Without it, PostGIS would calculate distance for every shop within 5 km, then sort. With it, the index walks the tree and returns candidates in approximate order. It’s not exact until the final sort, but it’s blindingly fast.

Act IV: The Geometry vs. Geography Schism (A Tale of Two Earths)

You’ll hit this around 2 AM. Your polygons on a city scale work fine. Then you try to calculate the area of a country and get numbers that would make a flat-earther nod approvingly.

Geometry: Treats the Earth as a flat Cartesian plane. Good for local projects (a few hundred km). Fast. Simple. Wrong for global distances.

Geography: Uses a spheroidal model (WGS84 by default). Accurate for distance, area, and bearing across the globe. Slower, because it’s doing real math.

My rule of thumb:

Store as geometry with SRID 4326 (lat/lon coordinates). It’s lightweight.
Use geography casting when you need Earth-aware calculations: geom::geography.
Index both – but a GIST on geography is larger and slightly slower.

Pro tip: For large tables with global queries, add a geog column as geography(Point, 4326) and index that. Then you can write clean queries like:

SELECT * FROM sensors
WHERE ST_DWithin(geog, ST_MakePoint(lon, lat)::geography, 50000); -- 50 km

No casting in the query means the index gets used without hesitation.

Act V: The Performance Trap (What They Don’t Put in the Brochure)

You’ve indexed everything. Queries are snappy. Then you deploy to production and… it’s slow again. Why?

Three silent killers:

Implicit casting in the WHERE clause

WHERE ST_DWithin(geom::geography, ...) – the cast happens before the index lookup. PostGIS can’t use a GIST on geometry for a geography query. Keep types consistent.
Using ST_Distance for filtering

   -- This is a full scan. Always.
   WHERE ST_Distance(geom, point) < 1000

ST_DWithin exists for a reason. Use it.

Over-indexing on large polygons A GIST index on a column full of complex polygons (e.g., country borders) can be huge. Consider storing a simplified “envelope” geometry for coarse filtering, then refine with exact ST_Intersects.

Real story: We had a table of 2M GPS traces. Queries were fast in dev (10k rows). In prod, EXPLAIN ANALYZE showed a bitmap heap scan—PostGIS was reading half the table anyway. Why? The distribution was clustered, but our random test data wasn’t. We added CLUSTER idx_restaurants_geom ON restaurants to physically reorder rows by spatial locality. Query time dropped from 4 seconds to 200ms.

Act VI: The Artistic Workflow (How to Think Spatially)

After two years of wrestling with PostGIS, I’ve developed a kind of intuition. It’s like learning to see negative space in a drawing. Here’s my mental checklist before writing any spatial query:

Draw it first – I keep a whiteboard or a quick QGIS window. Visualizing bounding boxes and intersections saves hours.
Start with the index – Write the query assuming the index will do the heavy lifting. Filter early, refine late.
Test with a point – Run EXPLAIN (ANALYZE, BUFFERS) on a single coordinate. Look for “Seq Scan” – if you see it, your index isn’t being used.
Think in meters, store in degrees – Use geography for distances, geometry for operations. Cast explicitly.
Batch your writes – A GIST index rebuild on 1M rows takes minutes. Do it nightly, not per insert.

Epilogue: You Are Now a Spatial Artist

PostGIS isn’t just a library. It’s a lens that changes how you see data. Suddenly every “near me” button, every delivery route, every heatmap becomes a solvable puzzle instead of a performance nightmare.

The journey from sqrt(lat^2 + lon^2) to elegant ST_DWithin with a GIST index is the difference between a child’s crayon scribble and a Monet. You’ve learned the brushstrokes. Now go paint some maps.

And when someone asks you, “Can you find all points within a polygon?” – smile, open your terminal, and whisper: “Watch this.”

JavaScript Memory Leaks: How to Find, Fix, and Prevent Them

Alex Aslam — Mon, 06 Apr 2026 18:20:51 +0000

It was 3 AM on a Tuesday. Or maybe Wednesday—the days blur when you’re chasing a ghost.

Our React dashboard, which had run beautifully for weeks, started dying. Slowly at first. A click took an extra second. Then five. Then the tab just… froze. I popped open Chrome DevTools, clicked the Memory tab, took a heap snapshot, and nearly choked. The app was eating 1.2 GB of RAM. For a dashboard that showed, at most, a thousand rows of data.

We didn’t have a bug. We had a memory leak. And it had been there for months, hiding in plain sight.

That night taught me something uncomfortable: You can write perfect‑looking code and still be slowly poisoning your users’ browsers. Memory leaks aren’t crashes—they’re death by a thousand cuts. The tab doesn’t throw an error. It just gets… tired. Sluggish. Then it dies.

Let me walk you through what I learned. Not as a list of bullet points, but as a journey into the invisible sculpture that is your app’s memory.

The Gallery of Forgotten References

Think of your JavaScript app as an art gallery. Every object, every variable, every closure is a painting on the wall. The garbage collector (GC) is the night janitor. He comes in periodically, looks around, and removes any painting that doesn’t have a visitor looking at it.

But the janitor is polite. He only removes something if nobody can reach it. If you still have a reference—a path from the root (like window or a global variable)—he leaves it. Forever.

A memory leak is simply this: you keep a reference to something you no longer need. The janitor sees it, shrugs, and walks away. And that painting stays on the wall, accumulating, until the gallery bursts at the seams.

As senior devs, we know the usual suspects. But knowing them and feeling them are different things. Let’s walk the gallery together.

Suspect 1: The Accidental Global

Remember when we all learned that omitting var, let, or const creates a global? We laughed. We said “I’d never do that.”

Then I found this in production:

function processUser(user) {
    result = heavyComputation(user); // forgot 'let'
    return result;
}

result became a global. It sat on window (or global in Node) forever. Every call overwrote it, but the previous object was still referenced? Actually, no—assignment overwrites the reference, so the old object is freed. But the real leak came later when a library attached something to window.result and never cleaned up.

The art lesson: Globals are permanent walls in your gallery. The janitor never touches them. If you must use a global, you’d better be ready to set it to null when you’re done.

How to find it: Run your app with 'use strict'. Or use ESLint’s no-undef. And in DevTools, check window for unexpected properties.

Suspect 2: The Clinging Closure

Closures are beautiful. They’re the watercolors of JavaScript—soft, elegant, capturing context. But they can also be a trap.

function createHeavyHandler() {
    const largeData = new Array(1000000).fill('*');
    return function() {
        console.log('handler called');
        // largeData is never used here!
    };
}
setInterval(createHeavyHandler(), 1000);

Every second, a new closure is created. That closure holds a reference to largeData because the function could use it. The GC can’t tell that you never actually touch largeData. So all those million‑element arrays stay alive. Forever.

I debugged a similar leak in a real app: an event handler that closed over a massive Redux store. The handler only used a single flag, but the entire store was captured. Each new listener added another copy of the store.

The fix: Be explicit. If a closure doesn’t need a variable, don’t let it capture it. Refactor, or use null to break the chain.

How to find it: Take heap snapshots and look at the retaining paths for large objects. You’ll see a closure context holding onto data you thought was gone.

Suspect 3: Forgotten Timers and Event Listeners

This one stung me the worst.

We had a single‑page app with modals. Each modal opened, fetched data, set up a setInterval to refresh that data every 30 seconds, and attached a resize listener to adjust the modal’s position.

When you closed the modal, we removed the DOM elements. But we forgot to call clearInterval and removeEventListener.

Result: Every modal you ever opened was still running its timer. The timer callback still held a reference to the (now detached) DOM nodes and the component’s state. The DOM nodes were gone from the page, but they were still in memory because the timer’s closure kept them alive.

The janitor couldn’t touch them. They were orphaned paintings in a hidden room.

The rule: For every setInterval, setTimeout, addEventListener, or Observer, you must have a cleanup. In React, that’s the useEffect cleanup function. In vanilla JS, it’s a destroy method.

How to find it: Use the Performance panel to record allocation timelines. If you see memory growing in a sawtooth pattern (up, down, but never back to baseline), you’ve got a leak. Then use heap snapshots to see what’s retaining those detached DOM nodes.

Suspect 4: The Ever‑Growing Cache

Caches are supposed to make things faster. But without a size limit or expiration policy, they’re just a slow leak in disguise.

const cache = {};
function fetchUser(id) {
    if (cache[id]) return Promise.resolve(cache[id]);
    return api.getUser(id).then(user => {
        cache[id] = user;
        return user;
    });
}

This is beautiful—until you’ve fetched ten million unique user IDs. Then cache holds every single one. Forever.

The art: A cache is a sculpture that must be pruned. Use Map with a TTL (time‑to‑live), or implement an LRU (least recently used) cache. Or use WeakMap when the keys are objects that can be garbage‑collected elsewhere.

How to find it: Look for large objects in heap snapshots that you didn’t expect. If you see a giant object with thousands of keys and you never intentionally built it, you’ve found your leak.

The Detective’s Toolkit

Over the years, I’ve built a mental checklist. When a user reports “the tab gets slow after an hour,” I don’t guess. I use:

Chrome DevTools → Memory → Heap snapshot

Take one before and after an action. Compare. The “Comparison” view shows you what’s been added and not freed.
Allocation instrumentation on timeline

Records every allocation with a stack trace. Lets you see exactly which function created the leaking object.
Performance monitor (under “More tools”)

Watch JS heap size in real time. If it never plateaus, you’re leaking.
Detached DOM nodes in heap snapshots

Filter for “Detached” – these are DOM elements no longer in the page but still referenced. A huge red flag.
Node.js ––inspect

Same DevTools, but for backend. Use process.memoryUsage() as a cheap health check.

Preventing Leaks: The Art of Letting Go

The most important shift in my thinking wasn’t technical. It was emotional. I stopped treating memory as infinite. I started treating every reference as a conscious choice.

Ask yourself, with every variable, every closure, every listener:

“When does this end? What cleans this up?”

If you can’t answer, you’ve painted a picture that will hang in the gallery forever.

Use WeakMap and WeakSet for metadata attached to objects that you don’t want to keep alive.
Prefer let and const over globals.
In React, always return a cleanup from useEffect.
For long‑lived apps (SPAs, Node services), periodically take heap snapshots in CI to detect regressions.
Use AbortController to cancel fetch requests and remove event listeners in one go.

The Human Truth

Memory leaks aren’t a mark of shame. They’re a natural consequence of writing dynamic, long‑running applications. Every senior I know has a war story. Mine involved a dashboard and a 3‑AM heap snapshot. Yours might be different.

But the art of memory management is the art of intentional forgetting. It’s about knowing when to hold on and when to let go. It’s a dance between you and the garbage collector—a silent partnership.

The janitor wants to help. He really does. But he needs you to stop pointing at paintings you no longer care about.

So go ahead. Open DevTools. Take a snapshot. See what’s still on your walls. And then, for the sake of your users’ RAM, start letting go.

The Event Loop, Microtasks, and Macrotasks: A Visual Explanation

Alex Aslam — Mon, 30 Mar 2026 20:42:54 +0000

I’ve spent the better part of a decade writing JavaScript that pretends to be synchronous. I’ve built real‑time dashboards, complex state machines, and APIs that handle thousands of requests per second. And for years, I thought I understood the event loop. I’d nod along to talks, recite “non‑blocking I/O,” and move on.

Then one night, I was debugging a bug that only happened in production. A setTimeout with 0 milliseconds was delaying a UI update just enough that a user could click a button twice. I added a Promise.resolve().then(), and suddenly the timing changed. I sat there, staring at my screen, realizing I didn’t actually know the order of things. I knew the words “microtask” and “macrotask,” but I didn’t feel them.

That night, I went down a rabbit hole that changed how I see our runtime. I stopped treating the event loop as a technical specification and started seeing it as a choreographed dance a piece of visual art that runs inside every Node.js process and every browser tab.

Let me take you on that journey. Forget the docs for a moment. Let’s look at the painting.

The Studio: Call Stack & Web APIs

Imagine your JavaScript runtime as a small, cluttered artist’s studio. In the centre is a single desk that’s the call stack. It’s a LIFO (last‑in, first‑out) stack of frames. Your code runs here, one function at a time, and it’s incredibly impatient. It can only do one thing at once.

Off to the side are the Web APIs (or Node.js APIs) think of them as the studio assistants. When you call setTimeout, fetch, or addEventListener, you aren’t actually doing the waiting yourself. You hand the task to an assistant, say “call me back when you’re done,” and immediately clear your desk for the next piece of work.

This is the first thing we internalize as seniors: asynchronous functions don’t run asynchronously; they just let you hand off work so you’re not blocked.

The Gallery: Task Queues (Macrotasks)

When an assistant finishes its work (a timer expires, a network response arrives), it doesn’t just shove the callback onto the stack. That would be chaotic the stack might be in the middle of something important. Instead, the assistant places a note on a gallery wall. That wall is the task queue (or macrotask queue).

The event loop is the curator. It watches the stack. If the stack is empty, it walks over to the gallery, picks up the oldest note (first in, first out), and places that callback onto the stack to run.

But here’s where my mental model broke that night: I thought there was one queue. There isn’t.

The gallery has multiple walls. One wall is for macrotasks setTimeout, setInterval, I/O, UI rendering events. Another, smaller, more exclusive wall is for microtasks.

The Private Collection: Microtasks

Microtasks are the VIPs of the JavaScript world. They include:

Promise callbacks (then, catch, finally)
queueMicrotask
MutationObserver (browser)
process.nextTick in Node.js (technically a separate queue, but similar priority)

When a Promise resolves, its .then callback doesn’t go to the macrotask wall. It goes to a microtask queue that sits right next to the curator’s desk.

And the curator (the event loop) has a strict rule:

After every single macrotask, before any rendering or the next macrotask, empty the entire microtask queue.

This changes everything.

The Choreography in Motion

Let’s watch a simple piece of code, not as logic, but as a ballet:

console.log('1');

setTimeout(() => console.log('2'), 0);

Promise.resolve().then(() => console.log('3'));

console.log('4');

The performance:

Stack: console.log('1') runs. Prints 1. Stack empties.
Macrotask: setTimeout hands a timer to an assistant. Assistant puts callback note on the macrotask wall (after 0ms).
Microtask: Promise.resolve().then schedules a microtask callback on the microtask wall.
Stack: console.log('4') runs. Prints 4.
Stack empty. Curator checks microtask wall. Finds the promise callback. Runs it. Prints 3.
Microtask queue empty. Curator now looks at macrotask wall. Finds the timer callback. Runs it. Prints 2.

Output: 1, 4, 3, 2.

If you ever thought setTimeout(…,0) meant “run immediately after this,” you’ve been fooled by the curator’s priorities. Microtasks always cut in line.

The Frame: Rendering

In the browser, there’s an extra act. Between macrotasks, the browser may decide to repaint. But microtasks happen before that repaint. This is a critical insight for performance‑sensitive UIs.

If you schedule a massive batch of microtasks (e.g., recursively chaining promises), you can starve the rendering. The page will feel frozen because the curator is stuck emptying an ever‑growing microtask list. You’ve probably seen this as “jank.”

As a senior, you learn to spot these subtle choreographic flaws. You learn that:

Use setTimeout when you want to yield to the UI or give other macrotasks a chance.
Use queueMicrotask or Promise when you need something to happen immediately after the current synchronous code, but before the next macrotask or render.

Node.js: The After‑Hours Studio

Node.js doesn’t have a rendering phase, but it has its own quirks. It has a process.nextTick queue that is even more VIP than microtasks it gets processed before microtasks, between each phase of its event loop.

The mental model I use now: the event loop is not a simple queue. It’s a roundabout with several exits, each with different priority lanes. Understanding that roundabout has saved me from:

Accidentally blocking the event loop with synchronous loops.
Mis‑ordering critical database updates and cache writes.
Building reliable real‑time systems where message order actually matters.

Why This Is Art

When I finally visualized this, I stopped seeing the event loop as a dry concept. I started seeing it as a kinetic sculpture. Every await, every setTimeout, every resolved promise is a tiny marble rolling down a track. The track has checkpoints microtask checkpoints, macrotask gates, rendering frames.

The art is in the orchestration. You, the developer, place the marbles. The engine moves them with absolute consistency, but it’s your understanding of the track that determines whether the sculpture is a chaotic mess or a graceful, predictable performance.

The best full‑stack developers I know don’t just write async/await. They feel where the microtasks land. They know that an await is syntactic sugar over a promise microtask. They use setTimeout(fn, 0) intentionally to “break” a synchronous loop and let the UI breathe.

They’ve stopped fighting the runtime and started composing with it.

Your Turn to Paint

Next time you see an order‑of‑operations bug, don’t just sprinkle async keywords. Draw the queues. Ask yourself: Is this a macrotask? A microtask? Where is the render frame?

You’ll find that the more you respect the choreography, the more the engine rewards you with silky‑smooth performance and deterministic behavior.

And if you ever need to explain it to a junior, skip the slides. Walk them through a whiteboard. Draw a circle for the stack, a wall for macrotasks, a smaller table for microtasks, and a little curator with tired eyes. It’ll stick.

JavaScript Engine Under the Hood: How V8 Compiles Your Code

Alex Aslam — Mon, 30 Mar 2026 20:32:32 +0000

Let’s be honest with ourselves for a second. We spend our days wrangling React hooks, tweaking Next.js configs, and arguing about whether tabs are better than spaces (they are, fight me). We treat JavaScript like a high-level, friendly tool.

But have you ever stopped in the middle of debugging a production memory leak, looked at your terminal, and thought: What the hell is actually happening here?

I had that moment about six years ago. I was optimizing a Node.js microservice that was choking under load. I threw more hardware at it. It didn’t work. I optimized my algorithms. Barely a dent. Finally, I had to admit that I didn’t actually understand the "black box" that runs my code.

So, I went down the rabbit hole of V8—the JavaScript engine that powers Chrome and Node.js. And what I found wasn’t just a compiler; it was a piece of performance art.

Let’s take a journey. Imagine your code isn’t just text; it’s a raw lump of marble. V8 is the sculptor. And trust me, it’s a weird sculptor.

Phase 1: The Parser (The Interrogator)

When you hit node server.js or refresh your browser tab, the first thing V8 does is not run your code. It interrogates it.

The engine doesn’t see const x = 10; as we do. It sees a stream of characters. The Parser takes that stream and performs a terrifyingly efficient act of structural comprehension.

It builds the AST (Abstract Syntax Tree) . This is the blueprint. But here is the humanized nuance: V8 is lazy. It’s the laziest overachiever I know.

If you’ve written a function that doesn’t get called immediately, V8 says, "Cool story, bro," and performs lazy parsing. It skips building the full AST for the inner scope of that function. It just checks for syntax errors so the page loads, but it doesn’t waste memory on code that isn’t running right now.

As a senior dev, you’ve probably felt this intuitively. You know that wrapping everything in an IIFE or loading a massive module at startup has a cost. That’s why. The engine is trying to be polite and save memory until you actually need that logic.

Phase 2: Ignition (The Bus Driver)

This is where the magic shifts from "reading" to "doing."

Back in the old days (pre-2017), V8 was a two-faced monster: Full-Codegen (fast startup) and Crankshaft (optimizations). It worked, but it was heavy. Now, we have Ignition.

Ignition is the interpreter. It takes that AST from the parser and spits out Bytecode.

If your code is the screenplay, bytecode is the stage directions. It’s not machine code (1s and 0s your CPU loves), but it’s a lot smaller and more efficient than the raw JS text.

Here is the human part: Bytecode is the first draft.

When Ignition runs, it starts executing your code immediately. It doesn’t wait to understand the "grand plan." It just gets the job done. But while it’s running, it’s watching you. It’s taking notes. It’s profiling.

It’s looking for the hot paths—the loops that run a thousand times, the function that gets called every millisecond.

And when it finds them? It whispers to the next guy.

Phase 3: Sparkplug & Maglev (The Pragmatists)

This is the part that blew my mind when I first learned it. We used to think V8 was just an interpreter plus an optimizing compiler. It’s not.

There is a middle ground now.

When a function becomes "hot" (called enough times), V8 doesn’t immediately send it to the super-optimizing compiler. That would be like sending a grocery list to a world-class architect. Overkill.

Instead, it uses Sparkplug.
Sparkplug is the "just get it done" compiler. It takes the bytecode and compiles it to machine code extremely fast. The code it produces isn’t winning any speed contests, but it’s faster than interpreting bytecode loop after loop.

Think of Sparkplug as the senior dev who writes "good enough" code to unblock the team. It works. It’s stable. It’s fast to compile.

But if a function is super hot—if it’s running thousands of times—V8 escalates. It sends the bytecode to Maglev (new as of V8 11.0).

Maglev is the middle manager. It does a quick analysis and creates a baseline optimized version. It’s a trade-off: a little more compile time for significantly faster runtime.

Why does this matter to you? Because if your app has "jank" or inconsistent latency, you’re seeing these tiers in action. The engine is constantly balancing the cost of compilation against the cost of execution. It’s a real-time economic decision happening inside your server.

Phase 4: TurboFan (The Perfectionist)

Now we enter the art gallery.

For the code that survives the heat—the critical inner loops, the heavy math, the complex class instantiations—V8 finally unleashes TurboFan.

TurboFan is the optimizing compiler. It takes the bytecode and the feedback collected by Ignition and makes a bet.

Here’s the risky part: Speculative Optimization.

JavaScript is dynamic. You can change a variable’s type whenever you want. The CPU hates that. So, TurboFan looks at your code and says, "I saw that in the last 10,000 runs, x was always a Number. I’m going to assume it stays a Number."

It then rewrites your logic into highly optimized, CPU-specific machine code that assumes x is a number.

If you keep passing it numbers? Congratulations. Your code now runs as fast as C++.

But if you change the type? If you pass a string or null?
TurboFan’s assumption breaks. It drops the optimized code, throws an error called deoptimization, and falls back to the slower bytecode.

This is the "art" part. Writing performant JavaScript isn’t just about using for instead of forEach anymore. It’s about keeping the engine happy. It’s about monomorphism.

If you write a function that takes a user object, and you always pass a User class instance with the same shape (same properties, same order), V8 says, "Ah, a classic. TurboFan, make this fast."

But if your function sometimes gets a { name, id } and sometimes gets a { name, age, address }, V8 panics. It has to handle the chaos. It uses the slow path.

The Human Lesson

When I realized this, my perspective on "clean code" changed.

Clean code isn’t just about readability for the next developer. It’s about predictability for the compiler.

Consistent Types: Initializing object properties in the same order isn’t just OCD; it’s a hint to V8’s hidden classes.
Small Functions: They’re not just for unit testing. Small functions are easier for TurboFan to analyze and optimize without hitting the "budget" limit (if a function gets too complex, V8 gives up optimizing it).
Avoiding delete: Using delete obj.property breaks hidden classes. It forces the engine to switch from "fast mode" to "dictionary mode" (slow mode). It’s like repainting a wall in a museum while the tour is happening.

The Unspoken Truth

Here is the truth they don't tell you in bootcamps: JavaScript is not slow. Your misuse of it is.

V8 is a masterpiece of engineering. It’s a Just-In-Time (JIT) compiler that does adaptive optimization at a scale that would make Java devs blush. It’s an interpreter, a baseline compiler, a mid-tier compiler, and an ultra-optimizing compiler all living in the same process, making millions of decisions per second to make your code look fast.

When you write code, you aren’t just instructing a computer. You are feeding an algorithm. The better you understand how that algorithm thinks—its preferences for stability, its obsession with types, its lazy parsing—the more you stop fighting the machine and start collaborating with it.

So the next time you deploy a massive monorepo or optimize a critical API route, don’t just think about the code. Think about the journey.

From raw text to bytecode. From a hot loop to TurboFan. From a lump of marble to a David.

That’s the art of the engine.

Geofencing in Turbo Native with Core Location

Alex Aslam — Sat, 28 Mar 2026 22:25:08 +0000

I still remember standing on the sidewalk outside a client’s office, watching the beta testers drive around the block for the twentieth time.

We had built a sleek Turbo Native app for a property management company. The web views were fast, the native navigation was smooth, and everyone was happy—until the product manager asked the inevitable question: “Can we automatically check in a technician when they arrive at a job site?”

My stomach dropped. I knew what this meant. We were about to step out of the cozy world of web views and into the wild, unpredictable wilderness of Core Location, geofencing, and background execution. And we had to make it work inside a Turbo Native wrapper—a hybrid app that was, at its heart, a web app pretending to be native.

What followed was a journey of frustration, late‑night debugging sessions, and eventually, a breakthrough that felt less like engineering and more like alchemy. This is the story of how we brought geofencing into Turbo Native—and how I learned that working with location is less about writing code and more about respecting the invisible boundaries of the physical world.

The Hybrid Trap

Turbo Native (formerly Turbo Native for iOS) is a gift to full‑stack developers. It lets you wrap your Rails web app in a native shell, giving you native navigation, push notifications, and a few other perks, while keeping the bulk of your UI in the familiar territory of HTML, CSS, and JavaScript.

But geofencing? That’s a different beast. The web has the Geolocation API, which works well enough for a one‑time “where am I” query. But for monitoring regions in the background—detecting when a user enters or leaves a predefined area—you need the full power of Core Location on iOS. And that lives in the native layer, not in the web view.

We had to figure out how to let the native side do the heavy lifting of monitoring, and then communicate those events to the JavaScript side so our Rails‑powered views could react. It was like teaching two musicians to play the same piece without a conductor.

The Art of Bridging

If you’ve worked with Turbo Native, you know that the bridge between Swift and JavaScript is usually the TurboSession and message handlers. You can inject a JavaScript interface into the web view, or use WKWebView’s postMessage mechanism. We chose the latter because it felt cleaner: the native side sends events to the web view, and the web view listens with window.addEventListener.

Here’s a stripped‑down version of what our Swift side looked like:

import CoreLocation
import UIKit
import WebKit

class GeofencingManager: NSObject, CLLocationManagerDelegate {
    private let locationManager = CLLocationManager()
    private weak var webView: WKWebView?

    func startMonitoring(webView: WKWebView) {
        self.webView = webView
        locationManager.delegate = self
        locationManager.requestAlwaysAuthorization()
        // Create a region (e.g., a job site)
        let center = CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194)
        let region = CLCircularRegion(center: center,
                                       radius: 100,
                                       identifier: "JobSite_123")
        region.notifyOnEntry = true
        region.notifyOnExit = true
        locationManager.startMonitoring(for: region)
    }

    func locationManager(_ manager: CLLocationManager, didEnterRegion region: CLRegion) {
        sendEventToWebView(name: "didEnterRegion", payload: ["identifier": region.identifier])
    }

    func locationManager(_ manager: CLLocationManager, didExitRegion region: CLRegion) {
        sendEventToWebView(name: "didExitRegion", payload: ["identifier": region.identifier])
    }

    private func sendEventToWebView(name: String, payload: [String: Any]) {
        guard let webView = webView else { return }
        let script = """
        window.dispatchEvent(new CustomEvent('\(name)', { detail: \(jsonString(payload)) }));
        """
        webView.evaluateJavaScript(script, completionHandler: nil)
    }
}

On the JavaScript side, we could listen like this:

window.addEventListener('didEnterRegion', (event) => {
  const identifier = event.detail.identifier;
  // Call Rails‑backed API or update the UI
  Turbo.visit(`/job_sites/${identifier}/arrive`);
});

Simple, right? It was, until we realized that background execution, battery life, and user permissions would turn this elegant bridge into a minefield.

The Invisible Trade‑offs

Geofencing is not a “set it and forget it” feature. It’s a negotiation between your app’s needs and the operating system’s constraints.

Permission Dialogues – Asking for “Always” location permission is a delicate moment. If you get it wrong, users will tap “Allow While Using” and your geofencing will stop working as soon as the app goes to the background. We learned to present a clear, empathetic explanation before the system dialog appeared—using a native screen that explained why we needed to track them even when the app was closed. This single change increased “Always” acceptance from 30% to 85%.

Battery Life – Every geofence you monitor consumes power. The system batches region updates to save battery, but you still need to be smart. We limited the number of active regions to 20 (Apple’s recommended maximum) and aggressively removed regions for completed jobs. We also used the accuracy parameter to balance precision with power: a radius of 100 meters was enough for our use case, and it let iOS use cell tower triangulation instead of constant GPS.

Testing in the Real World – You can simulate geofencing in the simulator, but it’s a lie. The real world has trees, buildings, and spotty GPS. We had to physically drive to locations to test. I spent an entire afternoon walking around a construction site with a debug build, watching logs, and adjusting radius values. It felt absurd, but it was the only way to understand how the system behaved.

The Web View’s Blind Spots

One of the hardest lessons came when we realized that the web view—our precious Turbo Native shell—has no knowledge of the native app’s lifecycle. If the user killed the app, our CLLocationManager would stop monitoring. When the app restarted, we had to re‑register all the regions. That meant persisting the list of active regions (we stored them in the app’s UserDefaults) and re‑starting monitoring on every launch.

We also had to handle the case where the app was launched in the background due to a geofence event. In that scenario, there’s no visible web view. We needed to perform a silent sync with the server and optionally show a local notification to alert the user. That meant adding a push notification layer (or using UNUserNotificationCenter) to communicate with the user when the app was in the background.

The Artistic Mindset

After weeks of wrestling with Core Location, I realized that geofencing is less like programming and more like painting with invisible ink. You define boundaries that no one sees, and you trust that the system will whisper to your app when a user crosses them. But the medium is messy: GPS drift, battery‑saving throttling, and user permissions can all blur the lines.

The art lies in setting expectations. We built a simple UI in the web view that showed the status of geofencing—whether it was enabled, how many active regions there were, and a history of recent events. This transparency helped users understand why the app was behaving the way it was. When a technician arrived at a site but didn’t get an immediate check‑in, they knew it was because the system was waiting for a stable GPS fix, not because the app was broken.

The Moment It Clicked

The breakthrough came during a user acceptance test. We sat in a van with a technician who was skeptical of the whole idea. He drove toward a job site, and as he pulled into the driveway, the app chimed and automatically opened the work order. His eyes widened. “It just knows,” he said.

That moment made all the complexity worthwhile. Geofencing, when done right, creates magic—a sense that the app is anticipating the user’s needs. And in a Turbo Native world, where most of the app is just a web view, that sprinkle of native magic can be the difference between a forgettable hybrid app and a beloved tool.

Lessons for Senior Full‑Stack Developers

If you’re embarking on this journey, here’s what I wish someone had told me before I started:

Respect the user’s privacy. Ask for “Always” permission only after explaining why. Give them a way to turn it off in settings. Build trust.
Test on real devices. The simulator is useful for logic, but the real world is where geofencing lives or dies. Walk, drive, and use Xcode’s debug location simulation to approximate real conditions.
Embrace async. Geofencing events are asynchronous and can happen when your web view isn’t even loaded. Design your JavaScript to be resilient: use an event queue if the page isn’t ready, and replay events when the view appears.
Monitor your own app. Add logging (with user consent) to see how often regions trigger. You’ll discover that users don’t always drive exactly through the center of your circles—adjust your radii based on real data.
Know your limits. iOS limits the number of monitored regions per app (currently 20). Design your system to activate and deactivate regions dynamically based on the user’s current location or time of day.

The Art of the Invisible

Geofencing in a Turbo Native app is ultimately about bridging two worlds: the web’s flexibility and the platform’s intimate awareness of the physical world. It’s a reminder that the best hybrid apps aren’t just web apps wrapped in native shells—they’re conversations between the two layers, each contributing what it does best.

Our technicians now start their day with a list of jobs, and the app quietly monitors their location. When they arrive, they don’t have to tap anything. The app knows. It feels like a sixth sense, and it’s become the feature that users rave about.

As senior developers, we often obsess over architecture patterns and performance metrics. But sometimes, the most rewarding work is the kind that disappears into the background—making the app feel less like software and more like an extension of the real world.

That’s the art. That’s the journey.

React Native + Rails synchronization with WatermelonDB

Alex Aslam — Sat, 28 Mar 2026 22:22:14 +0000

I still remember the Slack message that changed my entire approach to mobile development.

It came from our lead iOS engineer at 11:47 PM: “The app crashes when the train goes into the tunnel. Every. Single. Time.”

We had built a beautiful React Native app for field technicians. The Rails backend was solid. The API was RESTful. The UI was pixel‑perfect. But the moment the network got spotty—on the subway, in a basement, in the middle of nowhere—the app fell apart. Spinners that never stopped. Forms that failed to submit. Users who wanted to throw their phones into the nearest river.

We tried caching. We tried Redux persist. We tried local storage hacks. Nothing worked reliably. The app was a house of cards, and every network hiccup was a gust of wind.

That’s when I stumbled on a GitHub repository with a strange name: WatermelonDB. I read the README, and my heart started racing. This wasn’t another “just store some JSON in AsyncStorage” library. This was a full‑blown, reactive database for React Native, built for offline‑first apps with massive data sets.

The tagline said: “Build powerful React Native apps that work offline, with lightning-fast performance.”

I was skeptical. I’d been burned before. But three months later, after a journey of late nights, whiteboard arguments, and one unforgettable production deployment, I became a believer. This is the story of how we synchronized React Native with Rails using WatermelonDB—and how I learned that synchronization is less about code and more about art.

The Problem: Offline Isn’t Optional

Our use case was brutal. Field technicians in industrial sites needed to:

View thousands of work orders, even with zero connectivity.
Fill out detailed forms with photos, signatures, and checklists.
Sync everything automatically when they returned to the office or found a Wi‑Fi hotspot.

We tried the obvious: store API responses in AsyncStorage, show a cached version when offline, and queue mutations with a custom sync manager. It worked… for about a week. Then we hit the walls.

Performance – AsyncStorage is synchronous and blocking. Loading 5,000 work orders froze the UI for seconds.
Consistency – Redux persisted state could get out of sync with the backend. We had no way to know if the data was fresh.
Conflicts – When two technicians edited the same work order offline, the last one to sync won. We lost data.

We needed a database that was:

Fast – Queries in milliseconds, even with tens of thousands of records.
Reactive – The UI should update automatically when data changes, without manual refetching.
Sync‑aware – It needed a built‑in way to handle pull and push synchronization with a backend.

WatermelonDB checked every box.

WatermelonDB: The Database That Woke Up

WatermelonDB is not your typical mobile database. It’s built on top of SQLite (via @nozbe/watermelondb), but it adds a reactive layer that feels like magic. You define models with decorators, query with .observe(), and the UI re‑renders automatically when data changes.

The learning curve was steeper than I expected. It requires a different mental model: you’re working with observables and collections, not traditional imperative queries. But the payoff is immense.

Here’s a snippet of what a model looked like for us:

import { Model, field, date, relation } from '@nozbe/watermelondb';

export default class WorkOrder extends Model {
  static table = 'work_orders';

  @field('work_order_number') workOrderNumber;
  @field('title') title;
  @field('status') status;
  @date('scheduled_date') scheduledDate;
  @relation('users', 'assigned_to') assignedTo;
}

Simple, declarative, and reactive. But the real magic came when we added the sync engine.

The Sync Art: Bridging Rails and Watermelon

Synchronizing a WatermelonDB database with a Rails backend is an art form. It’s not a plug‑and‑play solution; you have to design both sides to speak the same language.

We spent a week sketching on a whiteboard, mapping out the synchronization lifecycle. We ended up with a two‑way sync strategy:

1. Pull: Getting the Initial Data and Updates

WatermelonDB’s synchronize method expects a pull function that fetches changes since a given timestamp. On the Rails side, we built an endpoint that accepted a last_synced_at parameter and returned:

A list of created/updated records (in a compact JSON format)
A list of deleted record IDs
A new timestamp for the next sync

We used updated_at columns to track changes. But we quickly realized that relying solely on timestamps could miss updates that happened in the same second. So we added a sync_version integer that increments on every change—a classic optimistic locking approach.

The Rails endpoint looked something like:

# /api/v1/sync/pull
def pull
  since = params[:last_synced_at] || Time.at(0)
  records = WorkOrder.where('updated_at > ?', since)
  deleted = WorkOrder.deleted.where('deleted_at > ?', since).pluck(:id)

  render json: {
    changes: records.map { |r| WorkOrderSerializer.new(r).as_json },
    deleted: deleted,
    timestamp: Time.current
  }
end

But we didn’t stop there. WatermelonDB allows you to send the entire dataset in chunks, so we implemented pagination for the initial sync to avoid loading 50,000 records at once.

2. Push: Sending Local Changes to Rails

Push was harder. WatermelonDB expects a push function that sends a batch of created, updated, and deleted records. On the Rails side, we had to process them in order, handle conflicts, and respond with success or failure for each record.

We created a POST /api/v1/sync/push endpoint that accepted an array of changes. Each change included:

id (local WatermelonDB ID)
table
action (create, update, delete)
data (the raw attributes)

The Rails controller had to:

Validate each change (permissions, data integrity)
Apply it to the database
Handle conflicts (if the server version was newer, we returned a “conflict” response so the client could resolve it)

This was the most complex part. We introduced a last_synced_at on each record to detect conflicts. If the server’s updated_at was newer than the client’s version, we rejected the push and sent the server version back for the client to merge.

The Art of Conflict Resolution

Conflicts are inevitable in offline‑first apps. You can’t avoid them; you can only manage them gracefully.

We implemented a three‑tier strategy:

Last‑write‑wins (LWW) – For non‑critical fields like notes or comments, we simply let the latest write (by timestamp) win. We stored a client_updated_at field on the client and used that to determine precedence.
Merge – For more complex data, like checklist items, we merged changes. If the technician added a new item offline and the office changed the description of another item, we combined both.
Manual resolution – In rare cases (e.g., conflicting signatures), we flagged the record and asked the user to resolve it during sync. This was a last resort.

WatermelonDB’s sync adapter made it possible to implement these strategies cleanly. We wrote custom resolvers that ran on the client after a conflict was detected, merging data or showing a modal.

The Performance Revelation

Once we had the sync working, we tested it with our production data set: 20,000 work orders, 500 technicians, and thousands of photos. The initial sync took about 90 seconds over a slow 3G connection—unacceptable.

We optimized in several ways:

Chunked sync – We broke the initial sync into pages of 500 records. WatermelonDB processes them in batches, so the UI stayed responsive.
Selective sync – We didn’t sync all work orders. Only those assigned to the technician or related to their location. We added WHERE assigned_to = ? on the pull endpoint.
Binary data – Photos were synced separately with a background upload queue, not through WatermelonDB. The database only stored local file references.

The final result: first sync in ~15 seconds, incremental syncs in <2 seconds, and the UI never dropped below 60fps.

Lessons from the Journey

Looking back, I realize that building this sync layer was less about coding and more about understanding the shape of our data and the reality of our users. We had to make trade‑offs:

Consistency vs. availability – We chose availability (the app works offline) and accepted eventual consistency. Users could see stale data for a few minutes, but they could always work.
Complexity vs. user experience – The sync engine added 30% more code to our codebase. But it eliminated 90% of the support tickets related to network issues. Worth it.

We also learned to respect WatermelonDB’s constraints. It’s not a relational database in the traditional sense—it’s a reactive object store with SQLite underneath. You have to design your models to match your access patterns, not the other way around.

The Art of Sync

If I had to distill this journey into one piece of advice for senior full‑stack developers, it would be this:

Synchronization is not a technical feature; it’s a product experience.

When you build an offline‑first app, you’re promising your users that their work will be safe, that the app will be fast, and that the data will eventually be where it needs to be. WatermelonDB gives you the tools—but you, the artist, must paint the picture.

You have to decide:

How fresh does the data need to be?
What happens when two people edit the same thing?
How do you communicate sync status without annoying the user?
How do you recover from sync failures?

These are design questions, not just engineering ones. And the best solutions come from walking in your users’ shoes—or, in our case, riding in their trucks, watching them work in basements and barns, and understanding that a spinning spinner is a betrayal of trust.

We deployed the new WatermelonDB‑powered app six months after that frantic Slack message. The first week, we held our breath. Support tickets dropped by 80%. The lead iOS engineer sent a new message: “The train tunnel test passed. It didn’t even blink.”

That’s the art. That’s the journey.

Turbo Native + offline-first strategies with Workbox

Alex Aslam — Thu, 26 Mar 2026 07:56:45 +0000

I still remember the knot in my stomach as we watched the demo.

We were standing in a converted barn in rural Vermont, holding our iPads up to show the client their brand‑new field service app. The barn had beautiful wooden beams, a lot of charm, and exactly zero bars of cellular signal. The app, a sleek Turbo Native wrapper around our Rails web app had loaded perfectly when we tested it in the office. But out here, with no network, it just showed a white screen and a spinning spinner that would never stop.

The client smiled politely. I wanted to disappear into the hay.

That day taught me something that no amount of architectural diagrams could have conveyed: Offline is not a feature. It’s a promise you make to your users. And if you’re building a hybrid app with Turbo Native, you’d better have a strategy to keep that promise when the world goes dark.

The Dream and the Reality

Turbo Native is a beautiful piece of technology. For those who haven’t used it: it’s part of the Hotwire ecosystem, designed to let you wrap your existing web app in a native shell, giving you the best of both worlds
native navigation and the flexibility of the web. You build one set of views in Rails (or any backend), and they render inside a native WebView. It’s fast, it’s elegant, and it makes senior full‑stack developers feel like they’ve found a cheat code.

But there’s a catch.

Turbo Native, out of the box, assumes you have a network. It loads URLs, caches them briefly, but if you’re offline, it fails. Gracefully? Not really. It fails with the same blank despair my iPad showed in that barn.

The client’s technicians would be working in basements, parking garages, and yes, rural barns. They needed to use the app view their work orders, fill out forms, take photos even when the network was a distant memory.

We needed an offline‑first strategy. And that’s when I rediscovered a tool I had previously dismissed as “just for marketing sites”: Workbox.

Workbox: Not Just for SPAs

If you’ve only seen Workbox used to precache static assets for a React app, you’re missing the real magic. Workbox is a library that sits on top of service workers, and service workers are the most underrated API on the web platform. They are a proxy between your app and the network, and when you combine them with Turbo Native, you can turn your hybrid app into a resilient, offline‑first machine.

But let’s be honest: service workers are also a pain to get right. They live in a weird space, they update in mysterious ways, and debugging them can make you question your career choices. Workbox abstracts the complexity into declarative strategies, but you still need to think like an artist not an assembly line worker.

The Art of Caching Strategy

The first mistake we made was thinking we could just precache everything. Throw the entire web app into the service worker at install time. That works for a simple site, but our app had thousands of work orders, user‑specific data, and a backend that changed daily. Precaching all of that would have been insane.

So we had to think about what to cache and how.

1. Static Assets: Cache‑First with a Fallback

The app shell CSS, JavaScript, images should be available offline. For these, we used Workbox’s StaleWhileRevalidate strategy. Users get the cached version instantly, and the service worker quietly updates it in the background. This gives the illusion of speed and resilience.

workbox.routing.registerRoute(
  ({request}) => request.destination === 'style' || request.destination === 'script',
  new workbox.strategies.StaleWhileRevalidate({
    cacheName: 'static-resources',
  })
);

2. API Responses: Network‑First with a Cache Fallback

For dynamic data like work orders, we used NetworkFirst. Try the network; if it fails, serve from cache. But here’s the art: you need to decide which requests get this treatment. For us, the home dashboard and individual work orders were critical. We also had to handle pagination and search caching every possible query would be wasteful.

We ended up with a hybrid: we cached the last‑viewed work orders and used a custom cache key based on the URL and the user ID. Workbox’s plugins allowed us to add custom logic.

3. Offline Writes: The Hardest Part

The real complexity came with mutations. Technicians needed to submit forms (complete a work order, add notes, take photos) even when offline. How do you handle that?

We initially tried to rely on the browser’s built‑in form submission, but it would fail and show an error. Not acceptable. So we built a tiny client‑side queue using IndexedDB. When the user submits a form offline, we intercept the request, store it in IndexedDB, and immediately update the UI optimistically. When the network returns, we replay the requests in order using Workbox’s background sync.

This part felt like surgery. We had to ensure idempotency, conflict resolution, and a user‑friendly UI that showed “pending sync” indicators. But when it worked when we could fill out a form in a dead zone, drive to a Starbucks, and watch the data silently sync it was pure magic.

The Turbo Native Twist

Here’s where it gets interesting. Turbo Native has its own navigation stack. It loads pages via Turbo.visit() and caches them in a memory‑based cache. If you’re offline, that cache is empty, and the app fails.

We had to make the service worker and Turbo work together. The key was to intercept requests at the service worker level before Turbo even sees them. If the service worker returns a cached response, Turbo thinks it came from the network. That means the entire navigation experience remains smooth, even offline.

But there was a gotcha: Turbo uses fetch for its requests, and service workers can respond to those. However, Turbo also maintains its own back‑forward cache. We had to be careful not to double‑cache or cause conflicts. The solution was to keep Turbo’s in‑memory cache short‑lived (which is default) and rely on the service worker for long‑term offline storage.

We also used Workbox’s NavigationRoute to handle the initial page loads, ensuring that the app shell was always available.

The Journey: From Panic to Pride

Looking back, the journey to offline‑first Turbo Native was not a straight line. It was a series of failures, each one teaching us something new:

We broke the service worker update flow and users were stuck on an old version. Learned to implement a version‑based cache busting and prompt users to refresh.
We cached API responses that contained sensitive data, then realized we needed to clear the cache on logout. Added a custom cache cleanup.
We tried to sync offline mutations without proper ordering, causing conflicts. Moved to a serial queue with retry logic.

But the moment that made it all worth it was when we returned to that barn. This time, we had the app open, and we deliberately turned on airplane mode. The app still showed the dashboard cached data. We clicked into a work order, added notes, attached a photo, and hit “Submit.” It showed “Saved offline.” Then we turned off airplane mode, and within seconds, the data appeared on our server.

The client’s eyes lit up. “So it just works? Anywhere?”

“Yes,” I said. “Anywhere.”

The Bigger Picture: Art, Not Engineering

What we built wasn’t just a technical solution. It was a piece of art. We had to understand the users’ context working in the field, in unpredictable conditions and shape the technology to fit their reality, not the other way around.

Offline‑first is an attitude. It’s about assuming the network is unreliable, and designing for that as the default. Service workers and Workbox give you the palette, but the composition is yours.

For senior full‑stack developers, this is the kind of work that matters. It’s not about following a recipe; it’s about understanding the medium web views, service workers, native shells and blending them into something seamless.

Your Turn

If you’re building a Turbo Native app and you haven’t yet considered offline, I urge you to. Start small: cache your static assets, then move to API responses, then tackle mutations. Embrace the complexity, because the reward is an app that works in elevators, on airplanes, and in the middle of nowhere.

And when you inevitably hit a wall, remember: the service worker is just a JavaScript file. You can debug it, you can version it, you can bend it to your will. It’s not magic, it’s just code. But the experience it enables? That’s the magic.