DEV Community: Anand Rathnas

When Your SPA Eats Your API Routes: Fixing the Cloudflare Worker vs React Router Conflict

Anand Rathnas — Sat, 25 Jul 2026 04:16:31 +0000

My affiliate tracking links were returning the entire React app instead of a 302 redirect.

Not a 404. Not a 500. A perfectly happy 200 with my SPA's HTML shell. As if the browser was saying: "Here's your single-page application! You wanted a redirect? Never heard of her."

TL;DR

If you serve a React SPA from Cloudflare/CloudFront as a static bundle, every URL that doesn't match a static file falls through to index.html. That includes your API-style routes like /go/*. Fix it by adding a routing branch in your Cloudflare Worker that intercepts those paths at the edge before the SPA bundle even loads.

The Setup

Jo4 has an affiliate tracking feature. When someone clicks a /go/partner-slug link, the server is supposed to:

Record the click (timestamp, referrer, etc.)
Return a 302 Found redirect to the partner's destination URL

Simple HTTP. The browser follows the redirect, the user lands on the partner's page, and we have a clean record of the click.

The backend API at jo4-api.jo4.io handles this perfectly. The endpoint receives the request, logs the event, and returns:

HTTP/1.1 302 Found
Location: https://partner-site.com/landing

The problem? Those requests never reached the backend.

What Was Actually Happening

Here's the request flow I expected:

Browser -> Cloudflare -> Backend API -> 302 redirect

Here's what was actually happening:

Browser -> Cloudflare -> Static SPA bundle -> 200 OK (index.html)

The SPA is deployed as a static bundle behind Cloudflare. Cloudflare's default behavior for SPAs is to serve index.html for any path that doesn't match a static file. That's the whole point of a SPA — React Router handles routing client-side.

But React Router had no route for /go/*. It didn't need one. These aren't client-side routes. They're server-side endpoints that need to hit the API.

So when someone clicked jo4.io/go/partner-slug:

Cloudflare received the request
No static file matched /go/partner-slug
Cloudflare served index.html (SPA fallback)
Browser got a 200 OK with HTML
React Router loaded, found no matching route
User saw... the app. Not a redirect. The app.

The affiliate click was never recorded. The partner never got their traffic. Nobody was happy.

The Fix: Edge Routing in the Cloudflare Worker

The key insight is embarrassingly simple once you see it: the routing decision needs to happen at the edge, before the SPA bundle is even considered.

Cloudflare Workers sit in front of everything. They see every request before it hits your static files, your origin, anything. That's where the routing belongs.

// Cloudflare Worker - simplified routing
async function handleRequest(request) {
  const url = new URL(request.url);

  // Affiliate tracking routes - proxy to backend API
  if (url.pathname.startsWith('/go/')) {
    const apiUrl = new URL(url.pathname, 'https://jo4-api.jo4.io');
    apiUrl.search = url.search;

    return fetch(apiUrl.toString(), {
      method: request.method,
      headers: request.headers,
      redirect: 'manual', // Don't follow the redirect — pass it through
    });
  }

  // Everything else — serve the SPA
  return fetch(request);
}

The redirect: 'manual' part is important. Without it, the Worker would follow the 302 itself and return the final page content. We want to pass the 302 straight through to the browser so it handles the redirect.

After the Fix

Browser -> Cloudflare Worker -> intercepts /go/* -> proxies to jo4-api.jo4.io -> 302 redirect
Browser -> Cloudflare Worker -> everything else -> serves SPA

The SPA never sees /go/* requests. They're handled and done before React even loads.

I also updated the AffiliateNotificationService URLs to use the new route structure, so notification emails and Slack messages all point to the correct /go/ paths.

Why This Bit Me

I've been building web apps for years. I know how SPA routing works. But here's the thing — when you're moving fast and deploying a new feature, you test the feature. You test the affiliate link creation, the click tracking endpoint, the redirect logic. You test it all through the API directly.

What you don't test is: "What happens when a real browser hits this URL through the full CDN/SPA stack?"

I was testing jo4-api.jo4.io/go/partner-slug directly. That worked fine. The bug only appeared when hitting jo4.io/go/partner-slug — through the SPA's Cloudflare distribution.

The Lesson

If you're running a SPA behind Cloudflare (or CloudFront, or any CDN with SPA fallback):

Your SPA will eat every URL that doesn't match a static file
Server-side routes need edge-level interception — don't rely on the SPA to "not handle" them
Test through the full stack, not just the API directly
Cloudflare Workers are the right place for this routing — they execute before anything else

The SPA fallback behavior is a feature, not a bug. It's doing exactly what it's supposed to do. The problem is assuming that "routes I didn't define in React Router" will somehow magically reach your backend. They won't. The CDN doesn't know the difference between a client-side route and a server-side route. You have to tell it.

Ever had your SPA swallow routes meant for your backend? What was your fix — Workers, nginx rules, or something else?

Building jo4.io - a URL shortener with affiliate tracking that actually redirects now.

Testing Cloudflare Workers Without Cloudflare: A Vitest Setup That Actually Works

Anand Rathnas — Thu, 23 Jul 2026 04:19:43 +0000

I added 3,059 lines of tests to our Cloudflare Worker. Not a single line uses miniflare. No Workers runtime simulation. Just Vitest, vi.stubGlobal('fetch', mockFetch), and focused assertions on the things that actually break in production.

Here's why that's the right call and how to set it up.

TL;DR

Cloudflare Workers are just JavaScript functions that receive a Request and return a Response. You don't need the Workers runtime to test most of the logic. Stub fetch, write unit tests for routing, caching headers, and redirect handling. Save integration tests for deployment verification. This approach is faster, simpler, and catches the bugs that miniflare would miss anyway.

The Setup

A Cloudflare Worker's entry point looks like this:

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);

    if (url.pathname.startsWith('/go/')) {
      return proxyTrackingRequest(request, env);
    }

    if (url.pathname.startsWith('/blog/')) {
      return proxyBlogRequest(request, env);
    }

    return proxyDefaultRequest(request, env);
  }
};

It's a function. It takes a Request. It returns a Response. You can test this without Cloudflare's runtime.

Here's the Vitest setup:

// vitest.config.js
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'node',
    globals: true,
  },
});

No special Workers environment. No miniflare plugin. Just Node.

Stubbing Fetch

The Worker delegates to your backend via fetch. Stub it:

import { describe, it, expect, vi, beforeEach } from 'vitest';
import worker from '../src/index';

describe('Cloudflare Worker', () => {
  let mockFetch;

  beforeEach(() => {
    mockFetch = vi.fn();
    vi.stubGlobal('fetch', mockFetch);
  });

  afterEach(() => {
    vi.restoreAllMocks();
  });
});

vi.stubGlobal('fetch', mockFetch) replaces the global fetch that the Worker calls internally. Your tests control exactly what the backend returns.

The Test That Caught a Production Bug

This is the test I'm most proud of:

it('does NOT set Cache-Control on tracking routes - clicks must not be cached', async () => {
  mockFetch.mockResolvedValue(new Response('', {
    status: 302,
    headers: { 'Location': 'https://merchant.com/product' }
  }));

  const request = new Request('https://jo4.io/go/abc123');
  const response = await worker.fetch(request, mockEnv, mockCtx);

  // Verify no cache headers on tracking routes
  expect(response.headers.get('Cache-Control')).toBeNull();
  expect(response.headers.get('CDN-Cache-Control')).toBeNull();
});

Why does this matter? Our tracking links (/go/*) record clicks. Every hit to /go/abc123 creates a unique jo4_cid (click ID) and records the visit. If Cloudflare caches the 302 redirect, subsequent clicks skip the backend entirely. The publisher's click count flatlines. The brand sees zero conversions. Everyone loses money.

Blog routes get cached aggressively. Tracking routes must never be cached. One misplaced Cache-Control header and affiliate tracking silently breaks.

This test runs in 2ms. It would catch a regression the moment someone refactors the proxy logic and accidentally applies caching globally.

Testing Redirect Handling

Another critical test: verifying the Worker doesn't follow redirects.

it('passes redirect: manual to fetch for tracking routes', async () => {
  mockFetch.mockResolvedValue(new Response('', {
    status: 302,
    headers: { 'Location': 'https://merchant.com/product' }
  }));

  const request = new Request('https://jo4.io/go/abc123');
  await worker.fetch(request, mockEnv, mockCtx);

  // The Worker must NOT follow the redirect itself
  expect(mockFetch).toHaveBeenCalledWith(
    expect.any(String),
    expect.objectContaining({
      redirect: 'manual'
    })
  );
});

Without { redirect: 'manual' }, the Worker follows the 302 to the merchant's site. The fetch call resolves to the merchant's HTML page instead of the redirect response. The click event is recorded, but the Worker returns a 200 with the merchant's HTML instead of a 302 that the browser follows. The user sees the merchant page inside the Worker's response context. It's a mess.

redirect: 'manual' tells fetch to return the 302 as-is. The Worker passes the redirect response through to the browser. The browser follows it. The click is tracked AND the redirect works correctly.

Testing Cache Headers on Blog Routes

The inverse of the tracking test: blog routes SHOULD be cached.

it('sets Cache-Control on blog routes', async () => {
  mockFetch.mockResolvedValue(new Response('<html>Blog post</html>', {
    status: 200,
    headers: { 'Content-Type': 'text/html' }
  }));

  const request = new Request('https://jo4.io/blog/some-post/');
  const response = await worker.fetch(request, mockEnv, mockCtx);

  expect(response.headers.get('Cache-Control')).toBeTruthy();
});

Blog content is static. Caching it at the edge reduces origin load and improves page speed. The test ensures blog routes always get cache headers, even after refactoring.

Simplifying the Production Code

Writing these tests exposed unnecessary complexity in the Worker itself. The proxyRequest function had a conditional cache flag:

// Before: conditional caching logic
async function proxyRequest(request, env, shouldCache) {
  const response = await fetch(targetUrl, {
    redirect: shouldCache ? 'follow' : 'manual',
    // ... other options
  });

  if (shouldCache) {
    response.headers.set('Cache-Control', 'public, max-age=3600');
  }

  return response;
}

After writing the tests, I realized the caching decision is entirely determined by the route type. There's no scenario where a tracking route should be cached or a blog route shouldn't. The conditional flag was adding complexity without flexibility.

// After: separate functions, no conditionals
async function proxyTrackingRequest(request, env) {
  return fetch(targetUrl, { redirect: 'manual' });
  // No cache headers. Ever.
}

async function proxyBlogRequest(request, env) {
  const response = await fetch(targetUrl);
  response.headers.set('Cache-Control', 'public, max-age=3600');
  return response;
}

Simpler code. Easier to test. Impossible to accidentally cache a tracking route.

Why Not Miniflare?

Miniflare is excellent for integration testing. It simulates the Workers runtime, KV stores, Durable Objects, and other Cloudflare primitives. If your Worker uses KV heavily or relies on Durable Objects, miniflare is the right choice.

But for our Worker, the logic is straightforward: route requests, set headers, handle redirects. The bugs that bite us are:

Cache headers on the wrong routes
Missing redirect: 'manual' on tracking requests
Incorrect path matching

None of these require a simulated runtime. They're logic bugs. Unit tests with mocked fetch catch them instantly.

Miniflare adds startup time, dependencies, and configuration complexity. For 3,059 lines of tests, the faster feedback loop of pure Vitest matters.

The Numbers

Metric	Value
Lines of tests added	3,059
Test execution time	~1.2 seconds
Dependencies added	0 (Vitest was already installed)
Miniflare config files	0
Production bugs caught by cache header tests	1 (and counting)

The Pattern

If your Cloudflare Worker is primarily a proxy that routes, caches, and redirects:

Use vi.stubGlobal('fetch', mockFetch) to control backend responses
Test cache headers per route type explicitly
Test redirect handling with redirect: 'manual' assertions
Keep tests fast -- no runtime simulation needed
Save miniflare for Workers that use KV, D1, or Durable Objects

The goal isn't 100% simulation fidelity. It's catching the bugs that cost money. A cached tracking link is a silent revenue killer. A test that runs in 2ms and prevents it is worth more than a full miniflare integration suite that takes 30 seconds to boot.

How do you test your Cloudflare Workers? Miniflare, Vitest, or something else? I'm genuinely curious if others have gone the lightweight route.

Building jo4.io -- affiliate tracking links that are tested to never be cached.

Why Auth0 E2E Tests Fail After Login: The localStorage Race Condition

Anand Rathnas — Mon, 20 Jul 2026 04:40:09 +0000

Your Playwright test logs into Auth0 successfully. The redirect completes. The app loads. You snapshot storageState() for subsequent tests. Every test after that gets 401 Unauthorized on API calls.

The login worked. The token didn't persist.

TL;DR

Auth0 SPA SDK v2 writes two keys to localStorage inside handleRedirectCallback(): the user identity and the access token. Playwright's waitForLoadState('networkidle') fires before these writes complete because they're synchronous DOM operations, not network requests. Snapshotting too early captures the user key but misses the access token. Fix: use page.waitForFunction() to poll for the exact access token key.

The Symptom

Here's what the test looked like:

// global-setup.ts
const page = await browser.newPage();
await page.goto('/');

// Auth0 redirects to login page
await page.fill('[name="username"]', process.env.TEST_USER);
await page.fill('[name="password"]', process.env.TEST_PASSWORD);
await page.click('[type="submit"]');

// Wait for the app to load after Auth0 redirects back
await page.waitForLoadState('networkidle');

// Save auth state for all tests
await page.context().storageState({ path: 'auth.json' });

This works 60% of the time. The other 40%, every subsequent test fails with 401.

The auth.json file holds the answer. On a failing run, it contains one localStorage key:

{
  "origins": [{
    "localStorage": [{
      "name": "@@auth0spajs@@::user::@@user@@",
      "value": "{\"sub\":\"auth0|abc123\",\"email\":\"test@example.com\"...}"
    }]
  }]
}

On a passing run, it contains two:

{
  "origins": [{
    "localStorage": [{
      "name": "@@auth0spajs@@::user::@@user@@",
      "value": "{\"sub\":\"auth0|abc123\"...}"
    }, {
      "name": "@@auth0spajs@@::your-client-id::your-audience::openid profile email",
      "value": "{\"body\":{\"access_token\":\"eyJ...\",\"token_type\":\"Bearer\"...}}"
    }]
  }]
}

The second key -- the one with the access token -- is missing on failing runs. The first key (user identity) is present either way.

The Root Cause

Auth0 SPA SDK v2 handles the OAuth callback in this sequence:

handleRedirectCallback() makes a network request to Auth0's /oauth/token endpoint to exchange the authorization code
The token response comes back
The SDK writes the user identity to localStorage (synchronous DOM operation)
The SDK writes the access token to localStorage (synchronous DOM operation)

Steps 3 and 4 are synchronous DOM writes. They're not network requests. Playwright's waitForLoadState('networkidle') triggers when there are no pending network requests for 500ms. That condition is met after step 2 completes -- the /oauth/token response arrived and there's nothing else in flight.

But steps 3 and 4 haven't executed yet. They're queued in the JavaScript event loop, waiting for the current microtask/macrotask to finish. networkidle fires, your test proceeds to storageState(), and you capture a snapshot mid-write.

Sometimes you catch both keys. Sometimes you only catch the first. It depends on exactly when the event loop gets to those writes relative to when Playwright reads localStorage. Classic race condition.

The Fix

14 lines:

async function waitForAuth0Token(page) {
  await page.waitForFunction(
    (clientId) => {
      const keys = Object.keys(localStorage);
      return keys.some(key =>
        key.startsWith('@@auth0spajs@@') &&
        key.includes(clientId) &&
        !key.includes('@@user@@')
      );
    },
    process.env.AUTH0_CLIENT_ID,
    { timeout: 30000 }
  );
}

This polls localStorage until the access token key appears. Not the user key (which arrives first and is useless on its own), but the key that contains the client ID and audience -- the one with the actual access token.

The updated setup:

// global-setup.ts
await page.click('[type="submit"]');
await page.waitForLoadState('networkidle');
await waitForAuth0Token(page);  // Wait for the ACTUAL token
await page.context().storageState({ path: 'auth.json' });

We keep waitForLoadState('networkidle') as a coarse wait for the page to settle, then add the precise wait for the specific localStorage key we need.

The waitForFunction Gotcha

One thing that cost me 30 minutes: the function signature.

// WRONG - opts is passed as the function's argument
await page.waitForFunction(fn, { timeout: 30000 });

// RIGHT - null is the function argument, opts is the third param
await page.waitForFunction(fn, null, { timeout: 30000 });

page.waitForFunction() takes three arguments: the function, the argument to pass to that function, and the options object. If you pass two arguments, Playwright treats the second as the function argument, not as options. Your timeout never gets applied, and you get the default 30-second timeout anyway (lucky coincidence in this case) or a confusing type error.

When you need to pass an actual argument and options:

await page.waitForFunction(
  (clientId) => { /* use clientId */ },
  process.env.AUTH0_CLIENT_ID,  // Passed to the function as clientId
  { timeout: 30000 }            // Playwright options
);

Why Not Just Add a Delay?

You could do this:

await page.waitForLoadState('networkidle');
await page.waitForTimeout(2000);  // "Should be enough"

It works until it doesn't. On a slow CI runner, 2 seconds isn't enough. On a fast local machine, you're wasting 2 seconds per run for no reason. Fixed delays in tests are a code smell that guarantees flakiness at scale.

The waitForFunction approach is deterministic. It resolves the moment the token appears, whether that's 50ms or 5 seconds after networkidle.

The Key Pattern

The Auth0 SPA SDK localStorage key follows this pattern:

@@auth0spajs@@::{clientId}::{audience}::{scope}

For example:

@@auth0spajs@@::abc123def456::https://api.jo4.io::openid profile email

The @@user@@ key follows a different pattern and only contains identity claims (sub, email, name). It does NOT contain the access token. If your test only needs to verify the user is logged in, the user key is sufficient. If your test makes API calls, you need the access token key.

Summary

What	Fires When	Good Enough?
`waitForLoadState('networkidle')`	No network requests for 500ms	No -- misses localStorage writes
`waitForTimeout(2000)`	After 2 seconds	Flaky -- arbitrary delay
`waitForFunction(checkLocalStorage)`	Token key exists in localStorage	Yes -- deterministic

The race condition exists because networkidle is a network-level signal, and localStorage writes are a DOM-level operation. They live in different layers. You need to wait at the layer where the state actually lives.

Hit this exact issue? Let me know in the comments -- I'm curious how many teams have independently discovered this race condition.

Building jo4.io -- E2E tested from Auth0 login to payout settlement.

Setting Up E2E Tests with Playwright + Auth0: The 5 Things That Took Longer Than the Tests Themselves

Anand Rathnas — Fri, 17 Jul 2026 04:12:12 +0000

We deleted approximately 10,000 lines of old EC2 Terraform infrastructure and replaced it with 1,637 lines of Playwright E2E tests that prove our entire "publisher gets paid" flow works -- from signup to settlement -- in seconds instead of months.

The tests themselves? Straightforward. The setup? Five separate rabbit holes, each deeper than the last.

TL;DR

Auth0 SPA SDK writes tokens to localStorage asynchronously after handleRedirectCallback(). Playwright's waitForLoadState('networkidle') fires before those writes complete. You need page.waitForFunction() to poll for the exact localStorage key. Also, you need a test-only controller gated by @ConditionalOnProperty to bypass time-based business logic. Here are all five things that cost me more time than writing the test assertions.

1. Auth0 Tokens and the localStorage Race

This was the biggest time sink. After Auth0 redirects back to your app, the SPA SDK calls handleRedirectCallback() which exchanges the authorization code for tokens. Those tokens get written to localStorage.

Playwright's waitForLoadState('networkidle') seems like the right thing to wait for. The token exchange is a network request, after all. But the localStorage writes that happen after the token exchange are synchronous DOM operations, not network requests. networkidle fires before they complete.

If you snapshot storageState() at this point, you capture a half-written auth state. The user key exists but the access token doesn't. Subsequent tests authenticate (they have the user identity) but get 401 on every API call (no access token).

The fix: poll for the exact key.

await page.waitForFunction(
  () => {
    const keys = Object.keys(localStorage);
    return keys.some(key =>
      key.startsWith('@@auth0spajs@@') &&
      key.includes('your-client-id') &&
      key.includes('your-audience')
    );
  },
  null,  // Must pass null as second arg
  { timeout: 30000 }
);

That three-argument form matters. waitForFunction(fn, opts) treats opts as the argument passed to the function. You need waitForFunction(fn, null, opts) to pass options to Playwright, not to your function.

I wrote a separate deep-dive on this localStorage race condition because it deserves its own post.

2. Bypassing the 14-Day Commission Hold

Jo4 has a 14-day hold on commissions before they're eligible for approval. This is a fraud prevention measure -- it gives brands time to detect invalid conversions. After approval, settlements run on a monthly cron.

For E2E tests, you can't wait 14 days. And you definitely can't wait for the first of next month.

The solution: a test-only Spring controller that's excluded from production builds at compile time.

@RestController
@RequestMapping("/api/v1/internal/test")
@ConditionalOnProperty(name = "jo4.e2e-test-mode", havingValue = "true")
public class TestSchedulerController {

    private final CommissionService commissionService;
    private final SettlementService settlementService;

    @PostMapping("/auto-approve-commissions")
    public ResponseEntity<Void> autoApproveCommissions() {
        commissionService.bulkAutoApproveExpiredPending(Long.MAX_VALUE);
        return ResponseEntity.ok().build();
    }

    @PostMapping("/trigger-settlement")
    public ResponseEntity<Void> triggerSettlement() {
        settlementService.processMonthlySettlements();
        return ResponseEntity.ok().build();
    }
}

@ConditionalOnProperty("jo4.e2e-test-mode") means this controller doesn't even get instantiated unless the property is explicitly set to true. It's not just gated at runtime -- Spring doesn't register the bean at all. No risk of it existing in production.

The bulkAutoApproveExpiredPending(Long.MAX_VALUE) call is the clever bit. The method normally checks if commissions are older than 14 days. By passing Long.MAX_VALUE as the threshold, every commission qualifies as "expired" and gets auto-approved immediately.

3. The Full Flow Test

With the Auth0 race condition solved and the time-bypass controller in place, the E2E test proves the entire monetization pipeline:

test('publisher gets paid - full flow', async ({ page }) => {
  // 1. Publisher signs up and creates a tracking link
  await loginAsPublisher(page);
  const trackingLink = await createTrackingLink(page, campaignId);

  // 2. Simulate a click and conversion
  await page.goto(trackingLink);
  await simulateConversion(page, trackingLink);

  // 3. Bypass the 14-day hold
  await fetch(`${API_URL}/api/v1/internal/test/auto-approve-commissions`, {
    method: 'POST',
    headers: authHeaders
  });

  // 4. Trigger settlement
  await fetch(`${API_URL}/api/v1/internal/test/trigger-settlement`, {
    method: 'POST',
    headers: authHeaders
  });

  // 5. Verify publisher sees the payout
  await page.goto('/dashboard/earnings');
  await expect(page.getByTestId('settlement-amount')).toBeVisible();
});

This runs in seconds. The real flow takes 14 days + waiting for the monthly cron. The E2E test proves every step works without the calendar being involved.

4. Deleting 10,000 Lines of Terraform

Before the Playwright setup, we had old EC2-based Terraform infrastructure for running Selenium tests. It provisioned EC2 instances, installed Chrome, managed security groups, and had its own deployment pipeline.

All of that infrastructure existed to run browser tests that were flaky, slow, and required dedicated compute.

Playwright runs locally or in CI with zero infrastructure. No EC2 instances. No security groups. No AMIs to maintain. We deleted every line of that Terraform and replaced it with a playwright.config.ts and a package.json script.

The 10,000 lines deleted versus 1,637 lines added ratio tells the story. Modern testing tools have made dedicated test infrastructure obsolete for most teams.

5. Keeping Test State Clean

The last surprise: Auth0 rate limits on the /oauth/token endpoint. If every test logs in fresh through the Auth0 UI, you'll hit rate limits fast in CI.

The fix is Playwright's storageState pattern:

// global-setup.ts — runs once before all tests
async function globalSetup() {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  await loginThroughAuth0UI(page);

  // Wait for the localStorage key (see problem #1)
  await waitForAuth0Token(page);

  // Save the authenticated state
  await page.context().storageState({ path: AUTH_STATE_PATH });
  await browser.close();
}

// playwright.config.ts
export default defineConfig({
  use: {
    storageState: AUTH_STATE_PATH,  // Every test starts authenticated
  },
});

One real login. Every test reuses the saved cookies and localStorage tokens. No rate limits. Tests run faster because they skip the Auth0 redirect dance.

What I'd Do Differently

If I were starting over, I'd set up the TestSchedulerController and the waitForFunction localStorage polling on day one, before writing a single test. Those two pieces are the foundation everything else depends on. I spent hours debugging test failures that were actually setup failures.

Also: don't bother with networkidle. For Auth0 flows, it's a trap. Use explicit waits for the exact state you need.

The Numbers

Deleted: ~10,000 lines of Terraform EC2 test infra
Added: 1,637 lines of Playwright tests
Full flow test time: ~12 seconds
Real flow time: 14 days + monthly cron
Auth0 logins per CI run: 1 (thanks to storageState)

Have you set up E2E tests with Auth0 or another identity provider? What was your biggest pain point? I'd bet it was the token storage timing.

Building jo4.io -- an affiliate marketplace tested end-to-end, from click to payout.

The Race Condition Between Bid Acceptance and Partnership Activation

Anand Rathnas — Tue, 14 Jul 2026 04:07:51 +0000

A brand clicks "Accept" on a publisher's bid. Nothing happens. The bid stays in SUBMITTED state. The brand clicks again. Still SUBMITTED. They email support.

Meanwhile, the publisher never got notified. The partnership never got created. And I'm staring at logs that show the accept endpoint returned 200 OK.

TL;DR

Notification failures inside a @Transactional method were rolling back the entire bid acceptance transaction. The fix: wrap notifications in try/catch because they're best-effort, not transactional. Also discovered two adjacent bugs: a missing guard on commission math and a bid status display priority issue when publishers have multiple bids on the same campaign.

The Acceptance Flow

When a brand accepts a bid, three things need to happen in sequence:

Update the bid status from SUBMITTED to ACCEPTED
Create a PartnershipEntity linking the brand and publisher
Notify the publisher that their bid was accepted

Here's what the code looked like:

@Transactional
public void acceptBid(Long bidId, Long brandId) {
    BidEntity bid = bidRepository.findById(bidId)
        .orElseThrow(() -> new ResourceNotFoundException("Bid not found"));

    validateBidOwnership(bid, brandId);
    validateBidStatus(bid, BidStatus.SUBMITTED);

    bid.setStatus(BidStatus.ACCEPTED);
    bidRepository.save(bid);

    PartnershipEntity partnership = createPartnership(bid);
    partnershipRepository.save(partnership);

    notificationService.notifyPublisherBidAccepted(bid);
}

Looks clean. Each step follows logically. The @Transactional annotation wraps everything in a single database transaction.

That's the problem.

The Root Cause

notificationService.notifyPublisherBidAccepted() makes an external HTTP call. Sometimes that call fails. Network timeout, email service down, rate limit hit -- doesn't matter. When it throws an exception, Spring's transaction manager catches it and rolls back the entire transaction.

The bid goes back to SUBMITTED. The partnership entity gets deleted. The brand sees no change.

And because the notification failure is the last step, there's no error visible to the brand. The endpoint already committed to returning a response. Depending on your error handling, this either swallows the exception entirely or returns a generic 500 that doesn't explain what happened.

The same pattern existed on the other side too:

@Transactional
public void submitBid(BidRequest request) {
    BidEntity bid = createBid(request);
    bidRepository.save(bid);

    notificationService.notifyBrandNewBid(bid);  // This can fail too
}

A publisher submits a bid, the notification to the brand fails, and the entire bid submission rolls back. The publisher thinks something went wrong. They submit again. Now you've got duplicate attempts and confused users.

The Fix

Notifications are best-effort. They should never roll back a successful database operation.

@Transactional
public void acceptBid(Long bidId, Long brandId) {
    BidEntity bid = bidRepository.findById(bidId)
        .orElseThrow(() -> new ResourceNotFoundException("Bid not found"));

    validateBidOwnership(bid, brandId);
    validateBidStatus(bid, BidStatus.SUBMITTED);

    bid.setStatus(BidStatus.ACCEPTED);
    bidRepository.save(bid);

    PartnershipEntity partnership = createPartnership(bid);
    partnershipRepository.save(partnership);

    try {
        notificationService.notifyPublisherBidAccepted(bid);
    } catch (Exception e) {
        log.error("Failed to notify publisher for bid {}: {}", bidId, e.getMessage());
        // Notification failure is logged but does NOT roll back the transaction
    }
}

Same treatment for notifyBrandNewBid():

try {
    notificationService.notifyBrandNewBid(bid);
} catch (Exception e) {
    log.error("Failed to notify brand for bid {}: {}", bid.getId(), e.getMessage());
}

The database operation succeeds. The notification is attempted. If the notification fails, we log it and move on. A retry mechanism or dead letter queue can pick it up later.

The Adjacent Bug: Commission Math With Null Values

While debugging the bid acceptance flow, I found another issue. When creating a partnership from an accepted bid, the commission calculation assumed conversionValue was always present and positive:

BigDecimal commission = conversionValue.multiply(commissionRate);

If a bid came through with a null or zero conversion value -- possible during testing or from a malformed API request -- this would throw a NullPointerException or produce a nonsensical commission.

The fix is a guard clause before the math:

if (conversionValue == null || conversionValue.compareTo(BigDecimal.ZERO) <= 0) {
    throw new IllegalArgumentException(
        "Conversion value must be positive, got: " + conversionValue
    );
}

Fail fast, fail loud. Don't let bad data propagate into commission calculations where it'll be much harder to trace.

The Display Priority Problem

One more thing surfaced during this investigation. A publisher can have multiple bids on the same campaign. They submit a bid, then withdraw it, then submit a new one. Now they have two bids: one WITHDRAWN, one SUBMITTED.

The UI was showing whichever bid it found first in the database. Sometimes that was the withdrawn one. The publisher would see "WITHDRAWN" and think their new bid didn't go through.

The fix was a displayPriority() method on BidStatus:

public enum BidStatus {
    ACCEPTED(1),
    SUBMITTED(2),
    COUNTERED(3),
    WITHDRAWN(4),
    REJECTED(5),
    EXPIRED(6);

    private final int displayPriority;

    BidStatus(int displayPriority) {
        this.displayPriority = displayPriority;
    }

    public int displayPriority() {
        return displayPriority;
    }
}

When rendering the UI, sort bids by displayPriority() and show the highest priority status. ACCEPTED beats everything. SUBMITTED beats WITHDRAWN. The publisher sees the status that actually matters.

The Takeaway

The pattern is simple: never let best-effort operations participate in your transaction boundary. Notifications, analytics events, audit logs, webhook fires -- if they fail, your core business operation should still succeed.

I think of it as the "airplane mode test." If the notification service went completely offline, should the brand still be able to accept a bid? Obviously yes. So the notification can't be inside the transaction.

Spring's @Transactional makes it easy to wrap everything in one big transaction. That's a feature when all your operations are database writes. It's a footgun when you mix in external calls.

Ever had a notification failure silently undo a user action? What was the blast radius? I'd love to hear about it in the comments.

Building jo4.io -- an affiliate marketplace where bid acceptance actually works.

Why We Silently Drop Clicks for Paused Campaigns (Instead of Returning 404)

Anand Rathnas — Sat, 11 Jul 2026 04:18:01 +0000

A brand pauses their affiliate campaign. What should happen when clicks and conversions still come in?

My first instinct was "return 404 for everything." Campaign is paused, resource doesn't exist, done. That instinct was wrong.

TL;DR

Two endpoints handle inactive campaigns differently — by design. Pixel tracking returns HTTP 200 with a transparent 1x1 GIF. Postback endpoints return HTTP 400 with "Campaign is not active." The asymmetry exists because the callers are fundamentally different.

Pixel Tracking: Return 200, Always

Affiliate pixels fire from third-party ad networks. A <img> tag buried in an ad creative, loaded by a browser on some publisher's website. The caller is a dumb HTML tag. It cannot:

Read the HTTP status code
Retry on failure
Alert anyone that something went wrong
Make decisions based on the response

If we return 404 for a paused campaign's pixel, nothing useful happens. The ad network doesn't know. The publisher doesn't know. The browser silently logs a failed image load in the console. Nobody acts on it.

Worse, some ad networks flag domains that return too many 4xx responses. They interpret it as a dead endpoint and may stop firing the pixel entirely — even after the campaign is reactivated.

So we return 200 and a transparent 1x1 GIF:

public ResponseEntity<byte[]> trackPixel(String campaignSlug, String publisherRef) {
    CampaignEntity campaign = campaignRepository.findBySlug(campaignSlug)
        .orElse(null);

    if (campaign == null || campaign.getStatus() != CampaignStatus.ACTIVE) {
        // Silent drop — return valid GIF, record nothing
        return ResponseEntity.ok()
            .contentType(MediaType.IMAGE_GIF)
            .body(TRANSPARENT_1X1_GIF);
    }

    // Active campaign — record the click
    clickService.recordClick(campaign, publisherRef);
    return ResponseEntity.ok()
        .contentType(MediaType.IMAGE_GIF)
        .body(TRANSPARENT_1X1_GIF);
}

Same response either way. The only difference is whether we call recordClick(). The pixel caller can't tell.

Postback Endpoints: Return 400, Loudly

Postbacks are server-to-server. A brand's backend calls our API when a conversion happens. The caller is software. It can:

Read the HTTP status code
Log errors
Alert developers
Stop sending conversions for paused campaigns

If we silently accept conversions for a paused campaign, the brand thinks commissions are accruing. They're not — we're dropping them. That's worse than an error. That's silent data loss that shows up as a billing discrepancy 30 days later during settlement.

public ResponseEntity<ConversionResponse> recordPostback(
        String campaignSlug, ConversionRequest request) {

    CampaignEntity campaign = campaignRepository.findBySlug(campaignSlug)
        .orElseThrow(() -> new NotFoundException("Campaign not found"));

    if (campaign.getStatus() != CampaignStatus.ACTIVE) {
        throw new BadRequestException("Campaign is not active");
    }

    ConversionEntity conversion = conversionService.record(campaign, request);
    return ResponseEntity.ok(mapper.toResponse(conversion));
}

400 with a clear message. The brand's integration logs it. Their developer sees it. They stop sending conversions or reactivate the campaign. The system is honest.

The Enum Fix

While working on this, I noticed conversion statuses were stringly typed:

// BEFORE
conversion.setStatus("APPROVED");
conversion.setStatus("REJECTED");

Two strings, no validation, no autocomplete, no compile-time safety. One typo — "APROVED" — and you have a conversion in a status that nothing in the system recognizes.

// AFTER
public enum ConversionStatus {
    PENDING,
    APPROVED,
    REJECTED,
    FLAGGED
}

conversion.setStatus(ConversionStatus.APPROVED);

Small fix. Eliminated an entire class of bugs. This is the kind of cleanup you do while you're already in the file — not worth a separate PR, but absolutely worth doing.

The Principle

The asymmetry comes down to one question: can the caller act on an error?

Caller	Can read status?	Can act on error?	Correct behavior
Pixel (img tag)	No	No	200 + silent drop
Postback (API)	Yes	Yes	400 + clear message

This applies beyond affiliate tracking. Any time you have multiple integration points for the same underlying operation, ask: who's calling, and what can they do with an error?

Webhook receivers that can retry? Return errors.
Fire-and-forget tracking pixels? Return 200.
Mobile SDKs that show error UI? Return errors.
Third-party script tags? Fail silently.

Do you have endpoints that intentionally return different status codes for the same underlying state? I'd be curious if others have hit this same design tension.

Building jo4.io — where even the error responses are a design decision.

Adding FTC Disclosure Gates to Our Affiliate Platform (And Why Server-Side Beats Client-Side)

Anand Rathnas — Thu, 09 Jul 2026 04:59:20 +0000

A brand creates an affiliate campaign on your platform. A publisher starts promoting it. Neither of them has acknowledged FTC disclosure requirements. Congratulations, you're now potentially liable.

The FTC requires that affiliate relationships be disclosed. Not "should be." Required. And if your platform makes it easy to skip that disclosure, you're part of the problem.

We added FTC disclosure gates to jo4 in 235 lines. Here's what we did and why the implementation details matter more than you'd think.

TL;DR

Campaign activation now requires FTC acknowledgment. Try to activate without it, you get a 400. Acknowledge first, then activate. Two API calls, one legal obligation met. Server-side enforcement, not a client-side checkbox.

The Flow

Three API calls, in order:

POST /campaigns/{slug}/activate
→ 400 Bad Request: "FTC disclosure acknowledgment required"

POST /campaigns/{slug}/ftc-acknowledge
→ 200 OK

POST /campaigns/{slug}/activate
→ 200 OK (status: ACTIVE)

The first activate call fails because ftcAcknowledged is false. The brand must explicitly call the acknowledgment endpoint. Then — and only then — can the campaign go active.

Why Not a Client-Side Checkbox?

The obvious implementation: add a checkbox to the campaign creation form. "I acknowledge FTC disclosure requirements." Required field. Done, right?

No. Here's why:

1. A checkbox can be bypassed.

Any browser extension, DOM manipulation, or automated script can check a box. The form submits with ftcAcknowledged: true without the user ever seeing the checkbox. You have zero proof of informed acknowledgment.

2. It doesn't protect API-only integrations.

Brands using Zapier, Pipedream, or direct API calls to create and activate campaigns never see your UI. If the gate is in the frontend, they skip it entirely. This isn't a hypothetical — we already have users creating campaigns via the jo4 API.

3. It doesn't survive SPA refactors.

You redesign the campaign form. A developer removes the checkbox because "we'll add it back in the new design." Or the checkbox component's state gets reset on a re-render. Or a feature flag accidentally hides it. Client-side gates are fragile because they depend on UI code that changes constantly.

4. It's not auditable.

With a server-side gate, we have a database record: who acknowledged, when, from which IP. With a checkbox, we have a form field that may or may not have been rendered when the user submitted.

The Implementation

The campaign entity gets a new field:

@Column(nullable = false)
private boolean ftcAcknowledged = false;

The activation service checks it:

public CampaignDTO activate(String slug, Long userId) {
    CampaignEntity campaign = findCampaignBySlugAndOwner(slug, userId);

    if (!campaign.isFtcAcknowledged()) {
        throw new BadRequestException("FTC disclosure acknowledgment required");
    }

    campaign.setStatus(CampaignStatus.ACTIVE);
    return mapper.toDTO(campaignRepository.save(campaign));
}

The acknowledgment endpoint:

public CampaignDTO acknowledgeFtc(String slug, Long userId) {
    CampaignEntity campaign = findCampaignBySlugAndOwner(slug, userId);
    campaign.setFtcAcknowledged(true);
    campaign.setFtcAcknowledgedAt(Instant.now());
    return mapper.toDTO(campaignRepository.save(campaign));
}

That's it. The gate is three lines in the activation method. The acknowledgment is four lines. The rest is tests.

The Tests: GAP-N Audit Mapping

Our E2E tests for this feature use a specific comment format:

// GAP-1: Campaign cannot be activated without FTC acknowledgment
@Test
void activate_without_ftc_returns_400() {
    // Create campaign, attempt activation
    var response = activateCampaign(campaignSlug);
    assertThat(response.getStatusCode()).isEqualTo(HttpStatus.BAD_REQUEST);
}

// GAP-2: FTC acknowledgment endpoint returns 200
@Test
void ftc_acknowledge_returns_200() {
    var response = acknowledgeFtc(campaignSlug);
    assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
}

// GAP-3: Campaign activates after FTC acknowledgment
@Test
void activate_after_ftc_acknowledge_succeeds() {
    acknowledgeFtc(campaignSlug);
    var response = activateCampaign(campaignSlug);
    assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
    assertThat(response.getBody().getStatus()).isEqualTo("ACTIVE");
}

// GAP-4: FTC acknowledgment persists across sessions
@Test
void ftc_acknowledged_survives_re_fetch() {
    acknowledgeFtc(campaignSlug);
    var campaign = getCampaign(campaignSlug);
    assertThat(campaign.isFtcAcknowledged()).isTrue();
}

The GAP-N prefix maps directly to our compliance audit document. When an auditor asks "how do you enforce FTC disclosure?", we point them to GAP-1 through GAP-4 and their corresponding test results. Each gap identified in the audit maps to a passing test.

This is a pattern I'd recommend for any compliance feature: name your tests after the audit finding they address. It creates a traceable chain from "regulatory requirement" to "passing CI check."

235 Lines. That's It.

The full diff:

1 new boolean column on campaigns table
1 new timestamp column (ftcAcknowledgedAt)
1 new endpoint (POST /ftc-acknowledge)
3 lines added to the activation method
4 E2E tests
Migration script

235 lines of changes. The smallest feature we shipped that quarter, and the one with the highest legal impact.

The Lesson

Compliance features feel like checkbox exercises. Literally — most people implement them as checkboxes. But the implementation details determine whether you're actually compliant or just performing compliance.

Server-side gates are:

Enforceable: works regardless of client (web, mobile, API, automation)
Auditable: database record with timestamp
Durable: survives UI refactors and redesigns
Testable: E2E tests prove the gate works, mapped to audit findings

A client-side checkbox is none of these things.

If your platform has any compliance requirement — FTC disclosure, GDPR consent, age verification — implement it as a server-side gate. It's the same amount of code. It's infinitely more defensible.

How do you handle compliance gates in your platform? Server-side, client-side, or something else? I'm curious how other indie devs approach this.

Building jo4.io — affiliate infrastructure that takes compliance seriously, even at 235 lines.

State Machines for Bid Negotiations: Modeling Offers, Counters, and Rejections

Anand Rathnas — Mon, 06 Jul 2026 05:17:42 +0000

A publisher submits a bid. The brand counters. The publisher accepts. Then the brand tries to withdraw. Is that legal? What if two bids are active on the same campaign — which one "wins" for display?

If you're reaching for a bunch of if/else checks scattered across your codebase, stop. You need a state machine.

TL;DR

We built BidStateMachineService to manage the full lifecycle of bid negotiations: DRAFT → SUBMITTED → ACCEPTED/REJECTED/COUNTERED → WITHDRAWN/EXPIRED. Each transition is validated. Each state has a displayPriority so we can resolve multiple bids on the same campaign to a single canonical status. 1,782 lines of tests cover every transition path.

The States

public enum BidStatus {
    DRAFT(10),
    SUBMITTED(70),
    COUNTERED(80),
    ACCEPTED(100),
    REJECTED(50),
    WITHDRAWN(20),
    EXPIRED(30);

    private final int displayPriority;

    BidStatus(int displayPriority) {
        this.displayPriority = displayPriority;
    }
}

That displayPriority field solves a real UI problem. When a publisher has three bids on the same campaign — one submitted, one countered, one rejected — what do you show in the dashboard? The answer: whichever has the highest priority.

public BidStatus getCanonicalStatus(List<BidEntity> bids) {
    return bids.stream()
        .map(BidEntity::getStatus)
        .max(Comparator.comparingInt(BidStatus::getDisplayPriority))
        .orElse(null);
}

ACCEPTED (100) beats COUNTERED (80) beats SUBMITTED (70). The publisher sees the most actionable state. Simple, deterministic, no special cases.

The Transition Map

Not every state can reach every other state. Here's the valid transition map:

DRAFT      → SUBMITTED, WITHDRAWN
SUBMITTED  → ACCEPTED, REJECTED, COUNTERED, WITHDRAWN, EXPIRED
COUNTERED  → ACCEPTED, REJECTED, WITHDRAWN, EXPIRED
ACCEPTED   → (terminal)
REJECTED   → (terminal)
WITHDRAWN  → (terminal)
EXPIRED    → (terminal)

In code, the state machine validates transitions before executing them:

private static final Map<BidStatus, Set<BidStatus>> VALID_TRANSITIONS = Map.of(
    BidStatus.DRAFT, Set.of(BidStatus.SUBMITTED, BidStatus.WITHDRAWN),
    BidStatus.SUBMITTED, Set.of(BidStatus.ACCEPTED, BidStatus.REJECTED,
        BidStatus.COUNTERED, BidStatus.WITHDRAWN, BidStatus.EXPIRED),
    BidStatus.COUNTERED, Set.of(BidStatus.ACCEPTED, BidStatus.REJECTED,
        BidStatus.WITHDRAWN, BidStatus.EXPIRED),
    BidStatus.ACCEPTED, Set.of(),
    BidStatus.REJECTED, Set.of(),
    BidStatus.WITHDRAWN, Set.of(),
    BidStatus.EXPIRED, Set.of()
);

public void transition(BidEntity bid, BidStatus newStatus) {
    Set<BidStatus> allowed = VALID_TRANSITIONS.get(bid.getStatus());
    if (!allowed.contains(newStatus)) {
        throw new InvalidStateTransitionException(
            "Cannot transition from %s to %s".formatted(bid.getStatus(), newStatus)
        );
    }
    bid.setStatus(newStatus);
    bid.setModifiedTime(Instant.now());
}

No if/else chains. No scattered validation. One map, one check, one exception type. Every invalid transition gets the same clear error.

Bid Templates: Reusable Pitches

Publishers pitch to multiple campaigns. Writing the same "Here's my audience, here's my reach, here's what I charge" pitch every time is tedious. Bid templates solve this:

@Entity
public class BidTemplateEntity {
    private Long publisherProfileId;
    private String slug;
    private String name;
    private String pitchText;
    private CommissionType preferredCommissionType;  // Optional preset
    private BigDecimal preferredRate;                // Optional preset
    private boolean deleted;
}

A publisher creates a template once, then applies it to any campaign. The template pre-fills the pitch and optionally suggests commission terms. The brand still negotiates — the template just eliminates copy-paste.

The Security Fix: Timing-Attack Oracle

This one was subtle and I'm a little embarrassed it shipped in the first place.

The original getTemplate() endpoint:

// BEFORE — vulnerable
public BidTemplateDTO getTemplate(String slug, Long requestingPublisherId) {
    BidTemplateEntity template = templateRepository.findBySlugAndDeletedFalse(slug)
        .orElseThrow(() -> new NotFoundException("Template not found"));

    if (!template.getPublisherProfileId().equals(requestingPublisherId)) {
        throw new ForbiddenException("Not your template");
    }

    return mapper.toDTO(template);
}

See the problem? If the template exists but belongs to someone else, you get 403 FORBIDDEN. If it doesn't exist at all, you get 404 NOT_FOUND. An attacker can enumerate template slugs by checking the HTTP status code. 404 = doesn't exist. 403 = exists, owned by someone else.

This is a classic timing-attack oracle. The fix is a single-query approach:

// AFTER — fixed
public BidTemplateDTO getTemplate(String slug, Long requestingPublisherId) {
    BidTemplateEntity template = templateRepository
        .findBySlugAndPublisherProfileIdAndDeletedFalse(slug, requestingPublisherId)
        .orElseThrow(() -> new NotFoundException("Template not found"));

    return mapper.toDTO(template);
}

Now both cases — doesn't exist and not yours — return the same 404. No information leakage. The query does the ownership check, not the application code.

This pattern applies everywhere: never fetch then check ownership. Query with ownership as a filter.

Notification Failures Don't Roll Back Bids

When a bid transitions, we send notifications — email, in-app, webhook. Early on, we had a bug where a notification failure (say, the email service was down) would roll back the entire bid state transition.

Publisher submits a bid. Email service times out. Bid reverts to DRAFT. Publisher is confused. Brand never sees the bid.

The fix: wrap notification calls in try/catch. The bid state transition is the primary operation. Notifications are secondary.

public void submitBid(BidEntity bid) {
    transition(bid, BidStatus.SUBMITTED);
    bidRepository.save(bid);

    try {
        notificationService.notifyBidSubmitted(bid);
    } catch (Exception e) {
        log.error("Failed to send bid notification for bid {}: {}",
            bid.getId(), e.getMessage());
        // Bid is already saved. Notification can be retried.
    }
}

This is a general principle: don't let secondary side effects roll back primary state changes. If the notification matters enough to guarantee delivery, use an outbox pattern or a retry queue. Don't couple it to the transaction.

1,782 Lines of Tests

The test file for BidStateMachineService is 1,782 lines. That sounds excessive until you think about what it covers:

Every valid transition (7 states × their valid targets = 10 transitions)
Every invalid transition (7 states × their invalid targets = 32 cases)
Display priority resolution with every combination of 2 and 3 concurrent bids
Template CRUD with ownership checks
The timing-attack fix (verifying both cases return 404)
Notification failure isolation (bid persists when notification throws)

Each test method reads like a specification:

@Test
void submitted_bid_can_be_countered() { ... }

@Test
void accepted_bid_cannot_be_withdrawn() { ... }

@Test
void display_priority_shows_accepted_over_countered() { ... }

@Test
void get_template_returns_404_for_other_publishers_template() { ... }

State machines are one of those patterns where exhaustive testing actually pays off. Every edge case you miss is a user stuck in a broken state with no way out.

When to Use a State Machine

Use a state machine when:

An entity has more than 3 statuses
Not every status can transition to every other status
Multiple actors can change the status (brand accepts, publisher withdraws)
You need an audit trail of transitions
The "what can I do next?" question depends on current state

Don't use a state machine when:

You have 2-3 simple statuses (ACTIVE/INACTIVE)
Transitions are always linear (PENDING → PROCESSING → DONE)
There's only one actor

For bid negotiations, the state machine eliminated an entire class of bugs: impossible transitions that the old if/else code allowed because someone forgot to check one condition in one handler.

Have you used state machines for business workflows? What patterns worked (or didn't work) for you? I'd love to hear about it.

Building jo4.io — where every bid state transition is validated, tested, and auditable.

Building an Affiliate Marketplace from Scratch: 14 Tables, 27 Services, Zero Money Movement

Anand Rathnas — Fri, 03 Jul 2026 04:47:29 +0000

Everyone told me the same thing: "If you're building an affiliate marketplace, you need a payments team."

No, you don't. You need a very clear opinion about what your platform should and shouldn't do. For jo4, that opinion is: we never hold, move, or touch money. 14 database tables, 27 services, 146 source files, 81 test files — and not a single money-movement API call.

Here's how.

TL;DR

jo4's affiliate marketplace connects brands (advertisers) with publishers (affiliates). Brands create campaigns, publishers apply with bids, and when a conversion happens, we record it and calculate commission. That's it. We never process payments. Settlement is a ledger entry that says "brand owes publisher X" — the actual payment happens externally.

The Money Flow (That Doesn't Flow Through Us)

This is the part that confuses people, so let me draw it out:

Brand connects their Stripe account via Stripe Connect OAuth
Customer buys something on the brand's site → Stripe checkout fires a webhook
jo4 receives the webhook → verifies it came from the brand's connected account
jo4 records the conversion and calculates commission (CPA or RevShare)
Monthly settlement scheduler sums what each brand owes each publisher
Brand pays publisher externally (wire, PayPal, whatever they agreed on)
Brand marks the settlement as paid in jo4

Steps 1-4 are automated. Steps 5-7 are the "boring" part that keeps us out of money transmission regulations.

Stripe Connect OAuth is used ONLY for webhook verification. We're confirming that checkout events actually came from the brand's connected Stripe account. We never initiate charges, transfers, or payouts through it.

The Commission Engine

Two models, both dead simple:

public enum CommissionType {
    CPA,        // Fixed amount per conversion ($10 per sale)
    REV_SHARE   // Percentage of sale (15% of order total)
}

The calculation happens in CommissionCalculatorService:

public BigDecimal calculateCommission(CampaignEntity campaign, BigDecimal saleAmount) {
    return switch (campaign.getCommissionType()) {
        case CPA -> campaign.getCommissionAmount();
        case REV_SHARE -> saleAmount
            .multiply(campaign.getCommissionRate())
            .divide(BigDecimal.valueOf(100), 2, RoundingMode.HALF_UP);
    };
}

No tiered rates, no graduated scales, no time-based multipliers. Those are features you add when you have paying customers asking for them, not when you're building V1.

Fraud Scoring

Every conversion gets a fraud score before it's counted:

Velocity check: How many conversions from this publisher in the last hour? Spike beyond 3x the rolling average = flag
Click-to-conversion time: If someone clicks an affiliate link and converts in under 2 seconds, that's suspicious. Humans don't buy that fast
IP clustering: Multiple conversions from the same IP range within a window

Flagged conversions aren't rejected — they're held for review. The brand decides. This is important: we don't make fraud decisions, we surface signals. The brand owns the risk.

Settlement: Monthly with Advisory Locks

The settlement scheduler runs on the 1st of every month at 2 AM UTC:

@Scheduled(cron = "0 0 2 1 * *")
public void runMonthlySettlement() {
    if (!tryAcquireAdvisoryLock(SETTLEMENT_LOCK_ID)) {
        log.info("Another instance is running settlement, skipping");
        return;
    }
    try {
        processSettlements();
    } finally {
        releaseAdvisoryLock(SETTLEMENT_LOCK_ID);
    }
}

PostgreSQL advisory locks handle distributed coordination. If you're running multiple instances (we are), only one will process settlements. The others gracefully skip.

The processSettlements() method groups all approved conversions by brand-publisher pair, sums commissions, and creates a settlement record:

@Data
public class SettlementEntity {
    private Long brandProfileId;
    private Long publisherProfileId;
    private BigDecimal totalAmount;
    private SettlementStatus status;  // PENDING, PAID, DISPUTED
    private YearMonth settlementPeriod;
}

Status starts as PENDING. The brand reviews it, pays the publisher however they agreed to, then marks it PAID in jo4. If there's a disagreement, it goes to DISPUTED and they work it out offline.

No Clawback Logic

This was a deliberate architectural decision. Many affiliate platforms implement clawback windows — if a customer refunds within 30 days, the commission is reversed.

We don't do this.

The brand sets the campaign terms. If they want a clawback window, they handle it in their settlement review before marking it paid. The risk is entirely on the campaign owner, which matches the industry standard for self-serve affiliate platforms.

Adding clawback logic would mean: tracking refund webhooks, implementing reversal entries, handling partial refunds, dealing with already-paid settlements, and building a dispute resolution flow. That's 4-6 weeks of work for a feature that solves a problem the brand can solve by waiting 30 days before paying.

The Database: 14 Tables

Here's the schema at a glance:

users / profiles — auth and account data
campaigns — brand's offer (commission type, rate, terms, FTC disclosure)
bids — publisher's application to a campaign
bid_templates — reusable pitch + commission presets
clicks — every affiliate link click, timestamped and IP-logged
conversions — confirmed sales with fraud scores
settlements — monthly brand-to-publisher ledger
stripe_connections — OAuth tokens for webhook verification
notifications — in-app alerts for bid status changes, new conversions
webhooks / webhook_events — outbound event delivery to brand's systems

14 tables. Each one maps to exactly one domain concept. No multi-purpose "events" table. No EAV pattern. No JSON columns for "flexibility."

27 Services, 146 Source Files

The service layer follows a strict pattern: one service per domain operation, not one service per entity.

CampaignActivationService — handles FTC gates, status transitions
BidStateMachineService — manages bid lifecycle (covered in the next post)
ConversionRecordingService — webhook → fraud check → commission calculation
SettlementSchedulerService — monthly aggregation + advisory locks
StripeConnectService — OAuth flow + webhook signature verification

Each service gets its own test file. 81 test files total. That's a test-to-source ratio of 0.55, which is about right for a platform where bugs mean incorrect money calculations.

What I'd Do Differently

Start with fewer tables. I could have shipped the MVP with 8 tables. Bid templates, fraud scoring, and the full notification system could have waited.

Skip Stripe Connect for V1. We could have started with manual webhook URL configuration instead of OAuth. The OAuth flow is slick but it delayed the launch by a week.

Use event sourcing for conversions. Right now, conversion status is a mutable column. If I were starting over, I'd make every status change an immutable event. Debugging "why was this conversion rejected?" would be trivial.

The Numbers

14 database tables
27 services
146 source files
81 test files
0 money-movement API calls
0 money transmission license requirements

That last line is the whole point. By refusing to move money, we removed an entire category of regulatory, security, and operational complexity. The tradeoff is that settlement is manual — but that's a feature, not a bug, when you're a two-person team.

Building an affiliate platform or something similar? What's your approach to the "should we move money" question? I'd love to hear how others have drawn that line.

Building jo4.io — affiliate marketplace infrastructure where the platform never touches a dollar.

From 30-Second Polling to Real Push Notifications

Anand Rathnas — Wed, 01 Jul 2026 01:52:57 +0000

Our notification bell was lying to users.

Not maliciously. It just... lagged. A publisher would submit a bid on a brand's campaign, and the brand wouldn't know for up to 30 seconds. In mobile app terms, 30 seconds is an eternity. Users were refreshing manually. Some thought notifications were broken entirely.

They weren't broken. They were polling. And polling on mobile is a sin we needed to repent for.

The Setup: How We Got Here

Our React Native app (Expo, managed workflow) had a NotificationBell component. Simple enough. It used RTK Query's pollingInterval to hit GET /api/v1/protected/notifications/unread-count every 30 seconds.

It worked on web. It worked on mobile. It "worked."

But here's what "worked" actually meant on a phone sitting in someone's pocket:

2,880 HTTP requests per day per active user (one every 30 seconds)
Battery drain from keeping the radio alive for each poll cycle
Zero delivery when the app was closed — if you killed the app, you got nothing until you opened it again
Wasted bandwidth — 99.9% of those responses came back with the same count

We were running a distributed denial-of-service attack against our own API. From our own app. On behalf of our own users.

The "Obvious" Solution: Expo Push Service

We're an Expo shop. EAS project ID configured, expo prebuild for native builds. The natural path was Expo Push Service — a single HTTP POST to exp.host/--/api/v2/push/send that fans out to both APNs and FCM. No Firebase SDK, no APNs HTTP/2 client, free up to 600 notifications per second.

We planned it. We spec'd it. We wrote the migration SQL.

Then we paused and asked ourselves: Do we really want a third-party proxy between us and Apple/Google for something this critical?

The Pivot: Direct FCM + APNs

We chose the harder path. Direct integration with both push services. No middleware, no proxy, no Expo dependency at runtime.

Here's why:

1. Zero runtime dependency. Expo Push Service is free and reliable, but it's still someone else's server. If exp.host goes down at 2 AM, our users don't get notified about a time-sensitive bid. With direct integration, the only failure points are Apple, Google, and us.

2. Full payload control. FCM v1 API and APNs have different payload structures, priority levels, and collapse keys. Going direct means we can tune each platform independently — badge counts on iOS, notification channels on Android, silent pushes for cache invalidation.

3. No token translation. Expo Push Tokens (ExponentPushToken[xxx]) are Expo's abstraction. Native device tokens are what FCM and APNs actually consume. By using getDevicePushTokenAsync() on the client instead of getExpoPushTokenAsync(), we skip the translation layer entirely.

The tradeoff? We had to implement JWT authentication for two different providers, each with their own signing algorithm, token format, and error semantics.

The Backend: Two JWT Dialects

FCM (Android): RSA-256 OAuth Dance

FCM v1 doesn't use a simple API key anymore. It requires a proper OAuth2 service account flow:

Load the Firebase service account's RSA private key (from an environment variable, never from the JSON file on disk)
Build a JWT with RS256, scoped to firebase.messaging
POST that JWT to Google's token endpoint
Get back an access token (valid ~1 hour)
Use that access token as a Bearer header on every FCM send
Cache it, refresh 5 minutes early

The key separation was deliberate. The jo4-prod-firebase-adminsdk-*.json file lives on the classpath for the client_email field. The actual private key comes from PUSH_FCM_SERVICE_ACCOUNT_KEY as a base64-encoded PEM at runtime. This means the JSON file in source control has no secrets.

APNs (iOS): EC-256 Provider Token

Apple's approach is simpler in some ways, weirder in others:

Load the .p8 key (EC private key, also from an env var)
Build a JWT with ES256, issuer = team ID, key ID in the header
That JWT is the auth — no token exchange, just attach it as a bearer header
Valid for 60 minutes, we refresh at 50

The HTTP/2 requirement is the curveball. APNs requires HTTP/2 — it will reject HTTP/1.1 connections. Java's HttpClient handles this natively (we set HttpClient.Version.HTTP_2 at construction), but it's the kind of thing that silently fails if you're using an older HTTP library.

The Token Lifecycle Problem

Push tokens have a lifecycle that most tutorials gloss over. A device token can become invalid for half a dozen reasons:

User uninstalled the app
User disabled notifications in system settings
Token was refreshed by the OS (happens periodically on both platforms)
User logged out and the token should no longer receive their notifications
User logged into a different account on the same device

We handle each case:

Registration (upsert): When the app boots and the user is authenticated, it calls POST /push-token. If that token already exists for a different user, we reassign it (device changed hands). If it's new, we create it.

Unregistration (logout): Before clearing the session, the app calls DELETE /push-token. This soft-deletes the token so the logged-out device stops receiving pushes. Critically, this happens before the auth token is cleared — otherwise the API call would fail with 401.

Auto-cleanup (delivery failure): When FCM returns UNREGISTERED (404) or APNs returns 410 Gone or BadDeviceToken, we soft-delete the token automatically. No stale tokens accumulate.

The soft-delete + hard-delete dance: Here's a subtlety. We use soft-deletes everywhere (BaseEntity pattern). But we also have a partial unique index: UNIQUE (push_token) WHERE deleted = false. If a user unregisters and re-registers the same token, the soft-deleted row would violate the uniqueness constraint. So before soft-deleting, we hard-delete any previously soft-deleted rows with the same token. It's a native SQL query that bypasses our ORM's @SQLRestriction("deleted = false") filter.

The @async + @Transactional Trap

This one nearly cost us a day.

Our push delivery runs inside @Async methods. When a token needs to be soft-deleted (delivery failure), we need a database transaction. The natural instinct is to extract a @Transactional private method.

This does not work.

Spring's @Transactional relies on AOP proxies. When you call a @Transactional method from within the same bean, the call goes through this, not through the proxy. The annotation is silently ignored. Your "transaction" is actually running without one.

Inside an @Async method, you're already past the proxy boundary. Internal calls to @Transactional methods are no-ops.

The fix: TransactionTemplate. Programmatic transaction management that works regardless of proxy context.

void softDeleteToken(UserPushTokenEntity token, String reason) {
    transactionTemplate.executeWithoutResult(status -> {
        userPushTokenRepository.hardDeleteSoftDeletedByPushToken(token.getPushToken());
        token.setDeleted(true);
        token.setDeleteReason(reason);
        userPushTokenRepository.save(token);
    });
}

Not glamorous. But it actually works. Every time.

The Mobile Side: Less Drama, More Plumbing

The React Native side was comparatively calm. A single usePushNotifications hook handles everything:

Permission request — Notifications.getPermissionsAsync() then requestPermissionsAsync() if needed
Token retrieval — Notifications.getDevicePushTokenAsync() (native token, not Expo token)
Backend registration — RTK Query mutation, best-effort (silently fails if backend is unreachable)
Foreground handling — setNotificationHandler to show banners even when the app is open
Cache invalidation — When a push arrives in the foreground, we invalidate RTK Query's UnreadCount cache tag. The NotificationBell re-renders with the fresh count. No polling needed.
Tap routing — When the user taps a notification, we extract actionUrl from the payload data and router.push() to the right screen

The hook stores the push token in a module-level variable (not React state, not Redux). Why? Because during logout, React state may be mid-teardown and Redux may be mid-reset. A simple module variable survives both.

The NotificationBell: From Polling to Push

Before:

const { data } = useGetUnreadCountQuery(undefined, {
  skip: !isAuthenticated,
  pollingInterval: 30000,  // The sin
});

After:

const { data, refetch } = useGetUnreadCountQuery(undefined, {
  skip: !isAuthenticated,
  // No polling. Push notifications invalidate the cache.
});

// Only refetch when user returns to the app (tab switch, unlock)
useEffect(() => {
  const sub = AppState.addEventListener('change', (next) => {
    if (appState.current !== 'active' && next === 'active' && isAuthenticated) {
      refetch();
    }
    appState.current = next;
  });
  return () => sub.remove();
}, [isAuthenticated, refetch]);

The difference: from 2,880 requests/day to maybe 20-30 (one per app foreground event). Server load dropped. Battery usage dropped. And notifications arrive instantly instead of up to 30 seconds late.

What We Shipped

Aspect	Before	After
Delivery mechanism	HTTP polling (30s)	FCM (Android) + APNs (iOS)
Background delivery	None	Full system-level push
Latency	0-30 seconds	Sub-second
Requests per user/day	~2,880	~20-30
Third-party dependency	None	None (direct to Apple/Google)
Token management	N/A	Auto-cleanup on delivery failure
Foreground behavior	Badge update on next poll	Instant banner + badge + sound

Lessons Learned

Expo Push Service is good. Direct is better. If you're serious about push reliability and payload control, go direct. The implementation cost is a few hundred lines of JWT plumbing.
@Async and @Transactional don't compose. Use TransactionTemplate for programmatic transactions inside async methods. This isn't a Spring bug — it's how AOP proxies work.
Soft-delete + unique constraints need careful choreography. Partial unique indexes (WHERE deleted = false) are powerful but require hard-deleting stale soft-deleted rows before creating new ones.
Store push tokens outside React state for logout. Module-level variables are ugly but survive the teardown chaos of a logout flow.
getDevicePushTokenAsync > getExpoPushTokenAsync if you're doing direct FCM/APNs. Skip the Expo token abstraction layer.
HTTP/2 is mandatory for APNs. Ensure your HTTP client is configured for it explicitly. Silent failures here are painful to debug.

Have you made the polling-to-push jump? What surprised you the most? Drop a comment below.

Building jo4.io — a modern URL shortener with analytics, bio pages, and an affiliate marketplace for creators.

I Made Claude Code Ding When It's Done (And It Changed My Workflow)

Anand Rathnas — Sun, 28 Jun 2026 01:49:39 +0000

You know that feeling when you ask Claude Code to refactor a module, switch to Twitter for "just a sec," and come back 12 minutes later to find it's been sitting there waiting for your input for the last 11?

Yeah. That was my Friday evening.

The "Are You Still There?" Problem

I've been using Claude Code as my daily driver while building jo4.io. It's brilliant at crunching through multi-file refactors, running tests, and fixing bugs. But here's the thing - when Claude finishes a task or has a question, it just... sits there. Silently. Like a polite intern who finished their work but doesn't want to interrupt your YouTube rabbit hole.

I needed a way for Claude to tap me on the shoulder. Something that says "Hey, I'm done" or "Hey, I need you" without me obsessively watching the terminal.

The Fix: 5 Lines of JSON

Claude Code has a hook system. I already wrote about PreToolUse hooks for blocking dangerous git commands. Turns out there's a Stop hook that fires every time Claude finishes responding and hands control back to you.

Here's the entire config I added to ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Funk.aiff",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

That's it. That's the whole thing.

What Happens Now

Every time Claude Code:

Finishes a task and waits for my next instruction
Runs into something it needs my input on
Completes a long test suite run
Asks me a clarifying question

...my Mac plays the Funk sound. You know the one - that satisfying little bonk that macOS has shipped since forever.

Why This Is a Game Changer

Before this, my workflow looked like:

1. Give Claude a task
2. Switch to browser
3. Forget about Claude
4. Come back 15 minutes later
5. Realize it's been waiting for 14 of those minutes
6. Feel guilty
7. Repeat

Now it's:

1. Give Claude a task
2. Switch to browser / grab coffee / stretch
3. *bonk*
4. Switch back immediately
5. Continue where we left off

My feedback loop went from "whenever I remember to check" to instant. I'm not exaggerating when I say this cut my average task turnaround in half - not because Claude got faster, but because I stopped being the bottleneck.

Pick Your Sound

macOS ships with a bunch of system sounds. Want something different? Try these:

# List all available system sounds
ls /System/Library/Sounds/

# Some favorites:
afplay /System/Library/Sounds/Glass.aiff    # Subtle, clean
afplay /System/Library/Sounds/Ping.aiff     # Classic notification
afplay /System/Library/Sounds/Hero.aiff     # Triumphant finish
afplay /System/Library/Sounds/Purr.aiff     # Gentle nudge
afplay /System/Library/Sounds/Funk.aiff     # The OG (my pick)

On Linux, you could use paplay, aplay, or even espeak "done" if you want Claude to literally tell you it's finished. On Windows WSL, powershell.exe -c "(New-Object Media.SoundPlayer 'C:\Windows\Media\notify.wav').PlaySync()" works.

Going Further: Conditional Sounds

Want different sounds for different situations? The Stop hook receives JSON on stdin with a last_assistant_message field. You could parse that to play a success sound when tests pass and an error sound when something breaks:

#!/bin/bash
input=$(cat)
message=$(echo "$input" | jq -r '.last_assistant_message // empty')

if echo "$message" | grep -qi "error\|fail\|blocked"; then
  afplay /System/Library/Sounds/Basso.aiff
else
  afplay /System/Library/Sounds/Funk.aiff
fi

Save that as ~/.claude/stop-sound.sh, make it executable, and point your hook at it instead.

The Full Picture

Combined with the PreToolUse hooks I set up earlier, my ~/.claude/settings.json now looks like:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Funk.aiff",
            "timeout": 5
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/block-git.sh",
            "timeout": 10
          },
          {
            "type": "command",
            "command": "~/.claude/block-cd.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

PreToolUse hooks keep Claude safe. Stop hooks keep me in the loop. Together they make Claude Code feel less like a tool and more like a teammate who knows when to wait and when to nudge.

These are the little things that make your day as a nerdy engineer. A five-line config change, a system sound you've heard a thousand times, and suddenly your entire AI-assisted workflow just clicks. It's not a groundbreaking feature. It's not going to make the front page of Hacker News. But it'll save you dozens of context-switch minutes every single day, and you'll wonder why you didn't set it up sooner.

Have you set up Stop hooks yet? What sound did you pick? Drop a comment - I'm genuinely curious what sounds people gravitate toward. Bonus points if you went the espeak route and have Claude literally talking to you.

Building jo4.io - a modern URL shortener with analytics, bio pages, and team workspaces.

We Built a 2048 Clone, Then Taught It to Play Itself

Anand Rathnas — Fri, 26 Jun 2026 01:50:48 +0000

We wanted a fun utility page for jo4.io/u/1024. Something people would open, mess around with for a minute, and then leave running in a tab. We ended up building a 2048-style tile-merging game with level-ups, confetti, and an AI that quietly takes over when you walk away.

Here's how we went from "let's make a simple game" to "wait, we need to implement a search tree."

The Game Itself

If you have played 2048, you know the drill. A 4x4 grid, tiles with numbers, slide them in four directions, matching tiles merge. Our twist: you start with base tiles [2, 4, 8] and the first milestone is 1024. Hit it, and you level up.

const LEVEL_CONFIG = [
  { base: [2, 4, 8],       milestone: 1024 },
  { base: [8, 16, 32],     milestone: 2048 },
  { base: [32, 64, 128],   milestone: 4096 },
  { base: [128, 256, 512], milestone: 8192 },
  { base: [512, 1024, 2048], milestone: 16384 },
  { base: [2048, 4096, 8192], milestone: 32768 },
];

Each level-up bumps your base tile values. Those tiny 2s and 4s that were cluttering the board? Gone. The cleanResidualTiles function sweeps anything below the new minimum base value. Suddenly the board opens up and you are playing a different game.

Six levels. The final milestone is 32,768. We have not reached it ourselves. The AI has.

Making It Feel Good

A tile game lives or dies on how it feels. We spent more time on animations than on the game logic itself.

Tiles slide via CSS top/left transitions with a smooth ease-out curve. When tiles merge, we run a 4-phase elastic bounce animation we call mergeBurst -- the tile shrinks to 60%, overshoots to 135%, settles back to 90%, then lands at 100%. It sounds over-the-top on paper. In practice it feels like tiles are made of marshmallow and it is deeply satisfying.

@keyframes mergeBurst {
  0%   { transform: scale(0.6); }
  30%  { transform: scale(1.35); }
  50%  { transform: scale(0.9); }
  70%  { transform: scale(1.1); }
  100% { transform: scale(1); }
}

On top of that, merged tiles get an expanding ring shockwave (mergeRing) that scales out to 1.8x and fades. Big merges (64+) flash the value across the board. Hit a milestone and confetti explodes from the center, 60 particles with randomized angles, velocities, and spin.

The key design decision: animations use transform: scale() only. Positioning uses top/left with transitions. This prevents the classic bug where CSS animations fight with position transitions and tiles teleport around the board.

The Idle Problem

We noticed something during testing. We would open the game, play for a bit, then get distracted by actual work. The tab would just sit there. Wasted screen real estate.

So we added autoplay. Go idle for 10 seconds and a countdown slider appears: "AI takeover in 30s." If you do not touch anything, the AI starts playing at one move per second. Press any key, click, or swipe to take back control instantly.

The UX matters here. A big arrow overlay (on a dark circle) shows which direction the AI is moving each turn. You can watch the AI think. It is weirdly hypnotic.

Teaching the AI: Expectimax Search

The first AI was just "pick a random valid move." It was terrible. Watching it play was painful.

Then we read John Googler's writeup on Markov Decision Processes for 2048 and realized the right approach is expectimax search -- a decision tree that alternates between the player picking the best move and the universe randomly placing a new tile.

Here is the core idea. The player moves (maximizing), then the game places a random tile (chance node). We alternate these layers and look ahead a few moves to evaluate which direction leads to the best expected outcome.

function expectimax(grid, depth, isPlayer, baseVals) {
  if (depth === 0) return evaluateGrid(grid);

  if (isPlayer) {
    let best = -1;
    for (const dir of ['left', 'up', 'right', 'down']) {
      const res = moveGrid(grid, dir);
      if (!res.moved) continue;
      const v = res.score +
        expectimax(res.grid, depth - 1, false, baseVals);
      if (v > best) best = v;
    }
    return best < 0 ? evaluateGrid(grid) : best;
  }

  // Chance node: average over ALL possible random tile placements
  const cells = []; // all empty cells
  for (let r = 0; r < 4; r++)
    for (let c = 0; c < 4; c++)
      if (grid[r][c] === 0) cells.push([r, c]);

  if (cells.length === 0) return evaluateGrid(grid);

  const weight = 1 / (cells.length * baseVals.length);
  let total = 0;
  for (const [r, c] of cells) {
    for (const val of baseVals) {
      const g = grid.map(row => [...row]);
      g[r][c] = val;
      total += weight *
        expectimax(g, depth - 1, true, baseVals);
    }
  }
  return total;
}

We run this at depth 4, which means 2 full look-ahead moves: player, chance, player, chance, then evaluate. This is enough for the AI to avoid obvious traps without taking seconds to compute.

The chance node is what makes this different from minimax. Instead of assuming the worst-case random tile, we average over every possible placement. This reflects reality -- the game is not adversarial, it is stochastic.

The Board Evaluation: Snake Weights

The evaluation function is where the real strategy lives. We use a snake-pattern weight matrix that assigns exponentially decreasing values in a zig-zag:

const W = [
  [32768, 16384, 8192, 4096],
  [  256,   512, 1024, 2048],
  [  128,    64,   32,   16],
  [    1,     2,    4,    8],
];

This encourages the AI to keep the biggest tile in the top-left corner and arrange tiles in descending order along a snake path. We also add a quadratic empty-cell bonus (empty * empty * 200) because empty space is safety, and a merge-potential bonus when adjacent tiles share the same value.

Corner-Lock: The Secret Sauce

The expectimax alone is decent but it has a weakness. Sometimes the highest-scoring move pulls the max tile out of the corner, and recovery is expensive. So we added a corner-lock filter.

function getBestMove(tiles, baseTileValues) {
  const grid = tilesToGrid(tiles);

  // Find the max tile and its corner
  let maxVal = 0;
  for (let r = 0; r < 4; r++)
    for (let c = 0; c < 4; c++)
      if (grid[r][c] > maxVal) maxVal = grid[r][c];

  const corner = findMaxCorner(grid);
  const maxInCorner =
    grid[corner[0]][corner[1]] === maxVal;

  // Score all valid moves
  const scored = [];
  for (const dir of ['left', 'up', 'right', 'down']) {
    const res = moveGrid(grid, dir);
    if (!res.moved) continue;
    const score = res.score +
      expectimax(res.grid, 3, false, baseTileValues);
    const keepCorner = !maxInCorner ||
      res.grid[corner[0]][corner[1]] === maxVal;
    scored.push({ dir, score, keepCorner });
  }

  if (scored.length === 0) return null;

  // Prefer corner-safe moves; corner-breaking = last resort
  const safe = scored.filter(m => m.keepCorner);
  const pool = safe.length > 0 ? safe : scored;
  pool.sort((a, b) => b.score - a.score);
  return pool[0].dir;
}

Every move is classified as either "corner-safe" (the max tile stays put) or "corner-breaking." The AI only considers corner-breaking moves when there is literally no other option. This single rule dramatically improved how far the AI gets.

Performance: Why Two Move Functions

You might notice we have two move functions: moveTiles (operates on Tile objects with IDs and animation flags) and moveGrid (operates on a raw 2D number array). The game UI uses moveTiles because it needs tile identity for React keys and animation state. The AI uses moveGrid because creating thousands of Tile objects per decision would be wasteful.

At depth 4, the AI evaluates hundreds of board states per move. Keeping the AI path as pure number-crunching -- no object allocation, no ID generation -- keeps each move well under 100ms on a modern browser.

The Result

The AI reliably reaches 1024, often gets to 2048, and occasionally pushes into the 4096+ levels. It is not perfect -- a deeper search or more sophisticated evaluation (monotonicity checks, smoothness penalties) could push it further. But for a browser game meant to be a fun background distraction, it hits the sweet spot.

You can watch it right now at jo4.io/u/1024. Open the page, play a few rounds, then put your hands down and watch the AI take over. It is oddly relaxing.

What is the highest tile you have reached -- manually or with an AI? Drop your score in the comments.

Building jo4.io -- a modern URL shortener with analytics, bio pages, and apparently, tile games.