DEV Community: Anand Rathnas

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.

How to Generate Printable Calendar PDFs (Free, No Signup, Works Offline)

Anand Rathnas — Wed, 24 Jun 2026 01:46:32 +0000

Every January, we go through the same ritual. Search "printable calendar 2026," click the first result, dodge three pop-ups, decline a newsletter, close an autoplay video, and finally download a generic PDF that doesn't quite fit what we need.

We got tired of the ritual. So we built a calendar PDF generator that does exactly what you'd expect and nothing you wouldn't.

It's free, at jo4.io/u/cal.

What It Does

The tool generates downloadable calendar PDFs in three view modes, each designed for a different use case.

Year View

A landscape PDF with all 12 months arranged in a 4x3 grid of mini calendars. Print one page, pin it to your wall, and you've got the entire year at a glance.

This is the view we use for long-range planning: vacations, project milestones, fiscal quarters. One sheet, no scrolling.

Month View

A landscape PDF showing a single month in a full-size grid. Each day gets its own cell with enough room to write in tasks, appointments, or reminders after printing.

If you've ever printed a Google Calendar and been disappointed by the layout, this is the fix. Clean grid, readable fonts, no clutter.

Weekly View

A portrait PDF with a daily planner layout. Each day gets hourly lines from 8 AM to 8 PM, so you can block out your schedule for the week.

This is useful for people who plan their days in time blocks. Print a fresh one every Monday, fill it in by hand, and keep it on your desk. Sometimes paper beats pixels.

The Day Selector (This Is the Part People Love)

Here's where it gets interesting. Below the view mode selector, you'll find a row of toggleable weekday buttons: Sun, Mon, Tue, Wed, Thu, Fri, Sat. By default, all seven days are selected.

Toggle off Saturday and Sunday, and now you have a work-week calendar.

Toggle off everything except Monday, Wednesday, and Friday, and you have a calendar that only shows the days your class meets.

You control which days appear on the final PDF. And you get to choose what happens to the days you deselect.

Grey Out vs. Remove

When you deselect a day, you pick one of two modes:

Grey Out keeps all seven columns in the grid, but the deselected days appear in light grey. The headers are muted, the day numbers are faded. You can still see them for context, but they visually recede. This is great when you want to focus on work days without losing track of the full week.

Remove eliminates the deselected day columns entirely. The remaining days expand to fill the available space. A Monday-through-Friday calendar in Remove mode gives each day more horizontal room, which means bigger cells and more writing space when you print.

We went back and forth on whether to include both options. Grey Out won for people who want context. Remove won for people who want space. So we kept both.

Practical Use Cases

The Work-Week Calendar

Select Month view. Toggle off Saturday and Sunday. Set mode to Remove. Choose "Monday" as the week start.

You get a clean five-column monthly calendar where every day cell is wider than usual. Print twelve of these (one per month), hole-punch them, and you have a work planner for the year.

The Academic Schedule

You have classes on Tuesday and Thursday only. Toggle off every other day. Set mode to Remove. Now your month view shows only the days you need. Each Tuesday and Thursday cell is wide enough to write in assignment due dates, lecture topics, or reading notes.

The Weekly Time Blocker

Switch to Week view. Keep all days selected, or remove weekends if you only plan work hours. Print a fresh weekly planner every Monday. The hourly lines from 8 AM to 8 PM give you a structured grid for time blocking.

We've found this is the fastest way to plan a week if you're a pen-and-paper person. Digital calendars are great for reminders and sharing. But there's something about physically writing "deep work" in a 2-hour block that makes it stick.

The Event Planning Calendar

Running a conference in October? Open Month view, select October 2026, and print it. The Year view also works here: print the full year and circle the key dates with a marker.

Paper Sizes and Week Start

Two small options that matter more than you'd think.

Paper size toggles between US Letter (8.5 x 11 inches) and A4 (210 x 297 mm). If you're in the US, you probably want Letter. Everywhere else, A4. Printing on the wrong paper size gives you awkward margins, so we made it easy to pick the right one.

Week start toggles between Sunday and Monday. The US convention starts weeks on Sunday. Most of Europe and ISO 8601 start on Monday. Whichever you prefer, the calendar grid adjusts accordingly.

Today's Date Highlighting

The generated PDF highlights the current date in bold blue. It's a small touch, but when you print a calendar and pin it up, it helps you orient immediately. You can spot "today" at a glance and start planning from there.

Privacy: Everything Runs in Your Browser

The entire tool is client-side. When you click "Download PDF," the calendar is generated right in your browser using jsPDF. No data is sent to any server. No API calls. No tracking of which dates you selected or which view you prefer.

This means it also works offline. Load the page once, disconnect from the internet, and you can still generate PDFs. Useful if you're on a plane, in a cafe with spotty Wi-Fi, or just someone who appreciates tools that respect your bandwidth.

How to Use It

Go to jo4.io/u/cal
Pick your view mode: Year, Month, or Week
Select the month/year (or week, depending on view)
Choose your paper size: Letter or A4
Set week start: Sunday or Monday
Toggle which days to include using the day selector buttons
Choose whether deselected days are greyed out or removed
Hit download

That's it. PDF appears in your downloads folder, ready to print.

No account creation. No email required. No watermarks. No "upgrade to pro for more features." The full tool is free.

Part of a Bigger Toolbox

The calendar generator lives at jo4.io/u/cal, part of our free tools suite at jo4.io/u. The suite includes 20+ utilities: JSON formatter, JWT decoder, password generator, QR code maker, and more. Same philosophy across all of them: client-side, no signup, no ads, just tools that work.

We built these because we use them daily. The calendar generator was the latest addition because we kept printing bad calendars from other sites and thinking "we can do better."

What does your ideal printable calendar look like? If there's a view or feature you'd want, drop it in the comments.

Building jo4.io - URL shortener with analytics, plus free tools at jo4.io/u including a printable calendar PDF generator.

We Built a Referral Program Tool Inside Our URL Shortener. Here's Why.

Anand Rathnas — Mon, 01 Jun 2026 01:55:21 +0000

Every SaaS founder eventually asks the same question: "How do I get my existing users to bring me new ones?"

The answer is referral programs. The problem is the tools.

The Problem with Referral Tools

I spent a week evaluating referral platforms for jo4. Here's what I found:

Tool	Price	What's Missing
Rewardful	$29-299/mo	No link analytics, Stripe-only payouts
FirstPromoter	$49-149/mo	Complex setup, steep learning curve
ReferralCandy	$47-299/mo	E-commerce only, no API

Every single one required a separate URL shortener for tracking. Every one locked you into Stripe for payouts. And the cheapest option started at $29/mo for basic features.

Meanwhile, I was already running a URL shortener with click analytics, device tracking, and geo-location built in. The referral link infrastructure was already there. I just needed to add programs, referrers, and reward tracking on top.

What Referral Kit Actually Does

The pitch is simple: create a referral program in 10 minutes, not 10 days.

For Program Owners

You create a program at /rk with a name, reward structure, and destination URL. You choose between two reward types:

Fixed Points — every conversion earns the referrer the same amount. "Refer a friend, earn 100 points."

Percentage — referrers earn a cut of the conversion value. "Earn 10% of every purchase your referral makes."

You get a public landing page at /rk/{your-program-slug} where anyone can sign up as a referrer. They pick a custom referral code (like JOHN20), enter their payout email, and get a unique tracking link.

For Referrers

After enrolling, you get a link like https://jo4.io/r/{shortUrl}. Share it anywhere. Every click is tracked with the same analytics jo4 already provides — device, location, referrer source, timestamp.

When someone converts (buys something, signs up, whatever your program defines as a conversion), you earn points. Your dashboard shows clicks, conversions, conversion rate, and pending/approved/paid points across all programs you're in.

The Conversion Flow

This is where it gets interesting. Program owners trigger conversions via API:

curl -X POST https://jo4-api.jo4.io/api/v1/public/referral/conversion \
  -H "X-Jo4-Conversion-Key: your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "programSlug": "summer-referral",
    "referralCode": "JOHN20",
    "conversionValue": 99.00,
    "externalId": "order_12345"
  }'

The API attributes the conversion to the referrer, calculates the reward (fixed or percentage), and creates a pending reward. The program owner reviews and approves. The referrer requests payout. The owner pays (offline — no Stripe lock-in) and marks it done.

Status flow: PENDING → APPROVED → PAYOUT_REQUESTED → PAID

No payment processor dependency. No percentage-of-a-percentage. You pay your referrers however you want — PayPal, Venmo, bank transfer, gift cards, crypto. We just track the state.

Why Points Instead of Cash

Most referral tools deal in dollars. We deal in points.

Points are flexible. "100 points = $10" works. So does "100 points = 1 free month" or "100 points = a t-shirt." The program owner defines what points mean. We track the math.

This matters for non-SaaS businesses. A nail salon running a referral program doesn't want to wire $10 to a customer's bank account. They want to give them a free manicure. Points let you do that.

The Technical Bits

Attribution Window

Every program has a configurable attribution window (default: 30 days). If someone clicks a referral link and converts within that window, the referrer gets credit. After the window closes, the conversion is organic.

Event Deduplication

The conversion API uses externalId for idempotency. Send the same order ID twice, and we only credit the referrer once. This matters when your payment webhook fires multiple times (and it will).

Test Mode

Prefix your externalId with test_ and the conversion validates against your API secret but doesn't persist. Test your integration without polluting production data.

Webhooks

Every state change fires a webhook if you've configured one:

referral.signup — new referrer enrolled
referral.conversion — conversion attributed
referral.reward.approved — reward approved by owner
referral.reward.paid — payout completed

Pipe these into Zapier, Slack, your CRM — whatever your workflow needs.

What I Got Right

Building on existing infrastructure. The URL shortener already had click tracking, device fingerprinting, and geo-location. Referral links are just URLs with attribution metadata. We didn't rebuild tracking — we extended it.

Offline payouts. Forcing Stripe integration would have narrowed our market to SaaS-only. The confirm-payout workflow is more manual, but it works for salons, clinics, restaurants, freelancers — anyone who pays referrers in-person or via their preferred method.

Points abstraction. Cash rewards sound simpler, but they're actually harder. Currency conversion, tax implications, minimum payout thresholds — points sidestep all of that. Let the program owner decide what points are worth.

What I Got Wrong

Underestimating the UI complexity. The /rk page serves three audiences: program owners viewing their programs, referrers viewing their enrolled programs, and new users discovering programs. Getting the information hierarchy right took more iterations than the entire backend.

The reward approval workflow. My first implementation auto-approved everything. Turns out program owners want to verify conversions before committing to payouts. Fraud is real, even in referral programs. Adding the PENDING → APPROVED step was the right call, but I should have started there.

The Numbers

The whole feature is:

1,084 lines of referral program service (Java)
3 new database tables with proper indexes and constraints
15+ API endpoints (public + protected)
6 new frontend pages
Full webhook integration
Test mode for safe integration development

And it ships with every jo4 plan. No add-on pricing. No "referral features start at Enterprise tier."

Running a referral program or thinking about adding one to your product? I'd love to hear what's working (or not) for you. Drop your experience in the comments.

Building jo4.io - URL shortener with analytics, QR codes, and now referral program management. Because your links should do more than redirect.

RevenueCat Integration for Indie SaaS: The Apple Tax Nobody Prepares You For

Anand Rathnas — Fri, 29 May 2026 01:47:54 +0000

I had Stripe working perfectly. Web dashboard payments, team billing, subscription upgrades and downgrades - all handled. Users happy. Revenue flowing.

Then I submitted my React Native app to the App Store.

The Problem

Apple's App Store Review Guideline 3.1.1 is clear: if your app offers subscriptions and the user can subscribe in the app, you must use Apple's In-App Purchase system. No exceptions. No "just link to your website." If you show a paywall, it goes through Apple.

This means:

Apple takes 15-30% of every transaction
You can't use your existing Stripe flow on iOS
You need a second billing system running in parallel
Both systems must keep the same user's subscription state in sync

I'd heard of RevenueCat as the standard way to handle this. What I hadn't heard was how many moving parts are involved when you already have a working billing system.

The Architecture Decision

The core question: where does the source of truth live?

Option A: RevenueCat is the source of truth, and your backend reads from it.

Option B: Your backend database is the source of truth, and RevenueCat sends webhooks to update it.

I went with Option B. Here's why:

I already had subscriptionTier, subscriptionStatus, and subscriptionExpiry on my UserEntity
All my API authorization logic checked these fields
Stripe webhooks already wrote to these same fields
I wasn't about to rewrite every @PreAuthorize check to call RevenueCat's API

So the plan: RevenueCat sends webhook events to my backend, and my backend updates the database. Same pattern as Stripe. How hard could it be?

The Implementation

Step 1: The Webhook Handler (Spring Boot)

RevenueCat sends a POST with a JSON payload containing an event object. The event has a type (like INITIAL_PURCHASE, RENEWAL, CANCELLATION) and an app_user_id that you set when the user logs in on mobile.

The key insight: use your database user ID as RevenueCat's app_user_id. This makes the webhook handler trivial - you get the user ID directly from the event, look up the user, and update their subscription.

// On mobile login, after getting the backend user profile:
await Purchases.logIn(String(profileData.response.id));

// In the webhook handler, the app_user_id IS your database ID:
Long userId = Long.parseLong(event.path("app_user_id").asText());
UserEntity user = userRepository.findById(userId).orElseThrow();

No mapping tables. No secondary lookup. Clean.

Step 2: Product ID Conventions

RevenueCat doesn't tell you the subscription tier directly. You infer it from the product ID you configured in App Store Connect. I used a simple convention:

// Product IDs: "jo4_pro_monthly", "jo4_proplus_yearly", etc.
SubscriptionTier determineTierFromProductId(String productId) {
    String lower = productId.toLowerCase();
    if (lower.contains("proplus")) return SubscriptionTier.PRO_PLUS;
    if (lower.contains("pro")) return SubscriptionTier.PRO;
    return SubscriptionTier.FREE;
}

Order matters - check proplus before pro, otherwise every Pro+ user gets classified as Pro. Ask me how I found that one.

Step 3: Event Deduplication

RevenueCat can send the same event multiple times (retries, network issues). Without deduplication, a single purchase could reset a user's URL count twice.

Redis made this straightforward:

private boolean tryMarkEventAsProcessed(String eventId) {
    String key = "revenuecat:webhook:event:" + eventId;
    Boolean wasSet = redisTemplate.opsForValue()
        .setIfAbsent(key, "processed", Duration.ofHours(24));
    return Boolean.TRUE.equals(wasSet);
}

Atomic setIfAbsent with a 24-hour TTL. If it returns false, we've already processed this event. Done.

Step 4: The Seven Lifecycle Events

This is where the complexity lives. RevenueCat sends seven different event types, and each one needs different handling:

Event	What Happens	Tier Change?	Reset URL Count?
`INITIAL_PURCHASE`	New subscriber	Yes - set tier	Yes
`RENEWAL`	Auto-renewal succeeded	Yes - confirm tier	Yes
`CANCELLATION`	User cancelled (but still has access until expiry)	No - keep tier	No
`EXPIRATION`	Access period ended	Yes - back to FREE	No
`BILLING_ISSUE`	Payment failed, grace period	No - pause status	No
`PRODUCT_CHANGE`	Upgrade or downgrade	Yes - new tier	No
`UNCANCELLATION`	User re-enabled auto-renew	No - restore ACTIVE status	No

The tricky one is CANCELLATION. Your instinct says "downgrade them." But no - they've already paid for the current period. You mark them as CANCELLED but keep their tier until EXPIRATION fires.

Step 5: The Mobile Side

On the React Native side, RevenueCat's SDK handles the App Store / Play Store payment sheets. You wrap it in a hook:

export function useSubscription(): SubscriptionState {
  const [offerings, setOfferings] = useState(null);
  const [customerInfo, setCustomerInfo] = useState(null);

  // Derived state from entitlements
  const isPro = customerInfo?.entitlements.active['pro'] !== undefined;
  const isProPlus = customerInfo?.entitlements.active['pro_plus'] !== undefined;

  const purchasePackage = async (pkg) => {
    const { customerInfo } = await Purchases.purchasePackage(pkg);
    setCustomerInfo(customerInfo);
    return true;
  };
  // ...
}

The subscription screen needs three states:

Web subscriber - they subscribed via Stripe on the web. Show "Managed on Web" with a link to the dashboard.
Active IAP subscriber - they subscribed through the app. Show "Manage in App Store/Play Store."
Free user - show the paywall with Pro and Pro+ packages.

Getting state 1 right was the part I almost missed. If a user has a Pro tier in the backend but no active RevenueCat entitlements, they're a web subscriber. Don't show them a paywall. Don't let them accidentally buy a duplicate subscription through Apple.

The Security Gotchas

Webhook Authentication

RevenueCat lets you set an authorization token in their dashboard. Your webhook endpoint verifies it:

if (webhookAuthToken == null || webhookAuthToken.isBlank()) {
    log.error("SECURITY: webhook auth token not configured");
    throw new AppException(UNAUTHORIZED, "Webhook processing unavailable");
}

Fail closed. If the auth token isn't configured (deployment mistake, missing env var), reject everything. Don't silently accept unverified webhooks.

Return 200 for Unknown Events

RevenueCat retries on non-200 responses. If you throw a 500 for an event type you don't handle, RevenueCat will retry it forever. Return 200 and log it:

default -> log.info("Unhandled event type: {}", eventType);
// ...
return ResponseEntity.ok().build();

The Deployment Lesson

The webhook auth token is a secret. I stored it in GitHub Secrets and injected it at deploy time through the workflow:

# In the deployment workflow .env template
REVENUECAT_WEBHOOK_AUTH_TOKEN=${{ secrets.REVENUECAT_WEBHOOK_AUTH_TOKEN }}

I initially had it in GitHub variables (not secrets) because "it's just a webhook token, not a database password." Nope. Any token that gates financial transactions is a secret. Period.

What I'd Do Differently

Start with the webhook handler first. I built the mobile paywall UI first, which meant I had a "Buy" button that worked but no backend to receive the purchase event. Webhook-first lets you test with RevenueCat's webhook tester before touching mobile code.
Use the same product ID naming convention across platforms. I initially had different Android and iOS product IDs. The determineTierFromProductId logic doesn't care about platform, so matching conventions saves headaches.
Test cancellation and expiration separately. These are different events with different behaviors. My first implementation treated CANCELLATION as EXPIRATION and immediately downgraded users. They were not thrilled.

The Result

Two billing systems (Stripe for web, RevenueCat for mobile) writing to the same user record. The user doesn't know or care which one is active. They just see their subscription tier reflected consistently across web, iOS, and Android.

Total implementation: ~250 lines of Java backend, ~120 lines of React Native hooks, ~350 lines of paywall UI. Plus 580 lines of tests, because the one thing worse than two billing systems is two untested billing systems.

Have you dealt with the Apple IAP mandate on an existing SaaS? I'd love to hear how you handled the dual-billing complexity. Drop your war stories in the comments.

Building jo4.io - a URL shortener with analytics for developers who'd rather not give Apple 30% but don't have a choice.

Why Our Android Build Was Signed with the Wrong Key (A Regex Cautionary Tale)

Anand Rathnas — Fri, 22 May 2026 01:47:58 +0000

"Your Android App Bundle is not signed with the correct key."

That was the Google Play Console rejection after what should have been a routine release. The SHA1 fingerprint on the uploaded AAB didn't match the expected upload key. We'd been deploying to the Play Store for weeks with no issues. What changed?

Nothing, as it turned out. The signing had been broken the whole time -- we just hadn't noticed until Google tightened its fingerprint check.

The Setup

We use Expo with expo prebuild --clean to generate the android/ directory before each build. Because it's regenerated every time, the entire android/ folder is gitignored. This means any customization to build.gradle needs to happen through a post-prebuild injection script.

Our scripts/release.sh runs after prebuild and uses Node.js to patch the generated build.gradle with the release signing configuration. It finds the release buildType block and replaces signingConfig signingConfigs.debug with signingConfig signingConfigs.release.

Sounds straightforward. But the regex doing this work had a subtle, devastating bug.

The Symptom

After release.sh ran, we expected build.gradle to look like this:

buildTypes {
    debug {
        signingConfig signingConfigs.debug
    }
    release {
        signingConfig signingConfigs.release  // patched
    }
}

Instead, it looked like this:

buildTypes {
    debug {
        signingConfig signingConfigs.release  // WRONG
    }
    release {
        signingConfig signingConfigs.debug    // WRONG
    }
}

The configs were swapped. Debug was using the release keystore. Release was using the debug keystore. The build succeeded (both keystores are valid), but the release AAB was signed with the debug key.

The Buggy Regex

Here's the regex our script used:

const patched = buildGradle.replace(
  /release \{[\s\S]*?signingConfig signingConfigs\.debug/,
  match => match.replace('signingConfig signingConfigs.debug', 'signingConfig signingConfigs.release')
);

The intent: find release { followed (lazily) by signingConfig signingConfigs.debug, then replace that debug with release.

The problem: release { appears twice in the generated build.gradle.

signingConfigs {
    debug {
        // ...
    }
    release {        // <-- FIRST occurrence of "release {"
        storeFile file("release.keystore")
        storePassword "..."
        keyAlias "..."
        keyPassword "..."
    }
}

buildTypes {
    debug {
        signingConfig signingConfigs.debug   // <-- target line
    }
    release {        // <-- SECOND occurrence of "release {"
        signingConfig signingConfigs.debug   // <-- intended target
    }
}

The lazy quantifier [\s\S]*? matched the first release { (inside signingConfigs), then expanded minimally until it found signingConfig signingConfigs.debug. The first signingConfig signingConfigs.debug it encountered was inside the debug buildType. So the regex matched from signingConfigs.release { all the way down to the debug buildType's signing config -- and replaced it.

This is the core misunderstanding: lazy quantifiers don't find the closest release { to the target. They find the first release { in the file, then minimize the gap from there. If the first match is in the wrong block, the lazy expansion crosses block boundaries to reach the target string.

The Fix

Anchor the regex to the buildTypes section:

const patched = buildGradle.replace(
  /(buildTypes\s*\{[\s\S]*?release\s*\{[\s\S]*?)signingConfig signingConfigs\.debug/,
  '$1signingConfig signingConfigs.release'
);

By requiring buildTypes { before release {, the regex skips the signingConfigs.release block entirely. The capture group grabs everything from buildTypes { through release { and any content before the signing config line. Then we replace just the signingConfig reference while preserving the surrounding structure.

The key difference:

BEFORE: /release \{[\s\S]*?signingConfig signingConfigs\.debug/
AFTER:  /(buildTypes\s*\{[\s\S]*?release\s*\{[\s\S]*?)signingConfig signingConfigs\.debug/

The buildTypes\s*\{ anchor ensures we're in the right block before we ever look for release {.

Bonus Bug: versionCode Stuck at 1

While debugging the signing issue, we found a second problem. Expo prebuild defaults versionCode to 1 in every generated build.gradle. Google Play requires versionCode to be strictly increasing -- you can never upload a version code equal to or lower than a previously uploaded one.

Our fix: auto-generate versionCode from epoch minutes in the release script:

VERSION_CODE=$(($(date +%s) / 60))

This produces a value like 29432517 that increases every minute. No manual tracking, no CI state to maintain, and no collisions as long as you don't release twice in the same minute.

The Node.js injection then patches this into build.gradle:

buildGradle = buildGradle.replace(
  /versionCode \d+/,
  `versionCode ${process.env.VERSION_CODE}`
);

Lessons Learned

1. Lazy quantifiers aren't always lazy enough.

The *? quantifier minimizes the match after fixing the start position. If your start anchor (release {) appears multiple times, the regex locks onto the first occurrence and expands from there. It doesn't backtrack to try the second occurrence unless the first one fails entirely.

2. When a pattern appears in multiple blocks, anchor to the surrounding context.

Don't match release { when you mean buildTypes { ... release {. The extra context eliminates ambiguity. This applies to any structured text you're patching with regex -- Gradle files, XML, YAML, anything with nested blocks.

3. Gitignored generated files need persistent injection scripts -- and those scripts need tests.

We tested the app. We tested the build. We never tested release.sh in isolation. A simple assertion -- "after running the script, the release buildType should have signingConfigs.release" -- would have caught this immediately.

4. Always verify build artifacts before pushing to a store.

A one-line check would have saved hours:

# Verify the AAB is signed with the correct key
jarsigner -verify -verbose -certs app-release.aab | grep "SHA1:"

If the fingerprint doesn't match your expected upload key, stop. Don't submit and hope for the best.

The Meta-Lesson

Regex on structured data is inherently fragile. Every time expo prebuild changes the generated build.gradle format, our regex could break in new and creative ways. The real long-term fix is to use Expo's config plugins to inject signing configuration declaratively, removing the regex entirely. We're migrating to that approach now.

But until then -- anchor your patterns, test your scripts, and verify your artifacts.

Have you been burned by regex matching across block boundaries? What's your approach to patching generated build files? We'd love to hear about it in the comments.

Building jo4.io -- a URL shortener with analytics, QR codes, and a mobile app that is now correctly signed.

CDN Cache Invalidation: Why Deleted URLs Still Redirect (And How We Fixed It)

Anand Rathnas — Wed, 20 May 2026 01:48:55 +0000

You deleted the URL. Redis says it's gone. The database confirms it. But users click the link and still get redirected to the destination. cf-cache-status: HIT. Cloudflare is happily serving a cached copy that nobody told it to forget.

The Problem

We run a URL shortener behind Cloudflare CDN. For performance, we cache redirect responses at the edge with a 2-hour TTL. This means popular short URLs resolve in under 50ms globally without touching our origin.

The issue surfaced when a customer deleted a short URL and then clicked it to verify. Still working. They tried again 30 minutes later. Still working. They opened a support ticket.

Same story with URL updates. A user changed the destination from https://old-site.com to https://new-site.com. The short URL kept redirecting to the old destination. OG metadata updates had the same problem — social cards showed stale titles and images because the HTML page was cached at the edge.

Three distinct mutations, all broken:

Delete URL — link stays alive via CDN cache
Update URL — old destination served from CDN, old metadata in Redis
Admin force-expire — neither Redis nor CDN gets invalidated

The Root Cause: Layered Caching, Partial Invalidation

Our caching architecture has two layers:

User Request → Cloudflare CDN (edge cache) → Spring Boot API → Redis (app cache) → PostgreSQL

When a URL is deleted, the service correctly invalidated the Redis cache. But it never told Cloudflare. The CDN layer continued serving stale responses until the TTL expired naturally.

The update path was worse. UrlService.updateUrl() wrote the new destination to the database but invalidated neither Redis nor Cloudflare. Reads hit Redis first, got the old cached value, and never saw the database update.

Admin operations were the worst. AdminService.forceExpireUrl() and AdminService.deleteUrl() updated the database directly and skipped both cache layers entirely. Admin code had been written as direct repository calls, bypassing the service-layer cache invalidation that regular user operations went through.

The Fix: Purge Both Layers on Every Mutation

Step 1: Add `purgeUrls()` to CloudflareService

Cloudflare exposes POST /zones/{zone_id}/purge_cache with a {"files": [...]} body. We wrapped it in a service method:

@Async
public void purgeUrls(List<String> urls) {
    if (!isEnabled() || urls == null || urls.isEmpty()) {
        return;
    }

    // Cloudflare API allows max 30 URLs per purge request
    List<List<String>> batches = partition(urls, 30);
    for (List<String> batch : batches) {
        purgeUrlBatch(batch);
    }
}

private void purgeUrlBatch(List<String> urls) {
    String endpoint = CLOUDFLARE_API_BASE + "/zones/" + zoneId + "/purge_cache";
    try {
        HttpHeaders headers = createHeaders();
        Map<String, Object> body = Map.of("files", urls);
        HttpEntity<Map<String, Object>> request = new HttpEntity<>(body, headers);

        ResponseEntity<CloudflareResponse> response = restTemplate.exchange(
            endpoint, HttpMethod.POST, request, CloudflareResponse.class
        );

        if (response.getBody() != null && response.getBody().isSuccess()) {
            log.info("Purged {} URL(s) from Cloudflare cache", urls.size());
        } else {
            log.warn("Cloudflare cache purge returned non-success for URLs: {}", urls);
        }
    } catch (Exception e) {
        log.warn("Failed to purge Cloudflare cache: {}", e.getMessage());
    }
}

Two design decisions here:

@Async (fire-and-forget). CDN purge should never block the user operation. If Cloudflare is slow or down, the delete/update still completes instantly. The cache will expire naturally via TTL as a fallback.

Batched in groups of 30. Cloudflare's API limits purge requests to 30 URLs per call. A single short URL can produce up to 3 cacheable URLs (UI page, API endpoint, custom domain), so this limit matters for bulk operations.

Step 2: Build the List of Cacheable URLs

Each short URL can be cached under multiple paths. We need to purge all of them:

private void addCacheableUrls(List<String> urls, String shortUrl, String customDomain) {
    // UI page (HTML with OG tags, served via Cloudflare CDN)
    urls.add(uiHost + "/a/" + shortUrl);
    // API endpoint (JSON, also cached by Cloudflare)
    urls.add(apiHost + "/api/v1/public/a/" + shortUrl);
    // Custom domain URL (if configured)
    if (StringUtils.isNotBlank(customDomain)) {
        urls.add("https://" + customDomain + "/a/" + shortUrl);
    }
}

For updates where the short URL or custom domain itself changed, we purge both old and new URLs:

private void purgeCloudflareCache(String shortUrl, String customDomain,
                                   String oldShortUrl, String oldCustomDomain) {
    List<String> urlsToPurge = new ArrayList<>();
    addCacheableUrls(urlsToPurge, shortUrl, customDomain);

    if (oldShortUrl != null && !oldShortUrl.equals(shortUrl)) {
        addCacheableUrls(urlsToPurge, oldShortUrl, oldCustomDomain);
    } else if (oldCustomDomain != null && !oldCustomDomain.equals(customDomain)) {
        urlsToPurge.add("https://" + oldCustomDomain + "/a/" + shortUrl);
    }

    if (!urlsToPurge.isEmpty()) {
        cloudflareService.purgeUrls(urlsToPurge);
    }
}

Step 3: Wire Into Every Mutation Path

This is where the original bug lived. We had to audit every code path that mutates URL state:

UrlService (user-facing operations):

updateUrl() — added Redis invalidation + Cloudflare purge
deleteUrl() — already had Redis invalidation, added Cloudflare purge

AdminService (admin operations):

forceExpireUrl() — added both Redis + Cloudflare invalidation
deleteUrl() — added both Redis + Cloudflare invalidation
refreshMetadata() — added Cloudflare purge (OG tags changed)

The admin fix required a dedicated helper since admin code was calling repositories directly:

private void invalidateUrlCaches(UrlEntity url) {
    urlCacheService.invalidateCache(url.getShortUrl());

    List<String> urlsToPurge = new ArrayList<>();
    urlsToPurge.add(uiHost + "/a/" + url.getShortUrl());
    urlsToPurge.add(apiHost + "/api/v1/public/a/" + url.getShortUrl());
    if (StringUtils.isNotBlank(url.getCustomDomain())) {
        urlsToPurge.add("https://" + url.getCustomDomain() + "/a/" + url.getShortUrl());
    }
    cloudflareService.purgeUrls(urlsToPurge);
}

One method. Both cache layers. Called from every admin mutation.

Why `@Async` Is the Right Call

CDN purge is a network call to Cloudflare's API. It adds 100-300ms of latency. If we made it synchronous:

User deletes a URL — waits an extra 200ms for Cloudflare confirmation
Cloudflare API is down — user's delete fails or hangs
Bulk operations — each URL adds another round-trip

With @Async, the user operation completes immediately. The purge runs in the background thread pool. If it fails, the cache expires naturally via TTL (2 hours max). The user never notices.

The tradeoff: there's a brief window (milliseconds to seconds) where the CDN might still serve stale content after an update. For a URL shortener, this is acceptable. For something like financial data, you'd want synchronous purge with error handling.

Lessons Learned

1. Cache invalidation has layers. If your architecture has CDN → Redis → Database, you need to invalidate from the outside in. Clearing Redis doesn't help if Cloudflare is still serving cached responses. Most requests never reach your app server when the CDN has a hit.

2. Admin code is a blind spot. Admin operations often bypass service-layer abstractions. They call repositories directly for flexibility, but that means they skip whatever cache invalidation the service layer provides. Audit every mutation path, not just the user-facing ones.

3. Fire-and-forget is correct for CDN purge. Don't block user operations on external API calls. Use @Async, log failures, and rely on TTL expiration as your safety net. The worst case is stale content for a bounded time window.

4. Enumerate all cacheable URLs. A single logical resource can exist at multiple CDN URLs. Miss one and you have a partial purge. Our short URLs have three: the UI page, the API endpoint, and the custom domain variant. All three need purging.

Ever been bitten by a stale CDN cache hiding a "deleted" resource? What's your cache invalidation strategy?

Building jo4.io - URL shortener with analytics, custom domains, and team workspaces.

How to Track Link Clicks with Meta Pixel for Facebook Retargeting

Anand Rathnas — Mon, 18 May 2026 01:49:34 +0000

You're running Facebook ads. You want to retarget people who clicked your links. But you're sending traffic to someone else's site (affiliate offer, client landing page, whatever) where you can't add your pixel.

Here's how to fire Meta Pixel on every click using jo4's built-in retargeting.

How It Works

When someone clicks your jo4 short link, the redirect page loads your Meta Pixel before sending them to the destination. Facebook sees the PageView event with your pixel ID.

User clicks jo4.io/abc123
    ↓
Pixel fires (PageView event)
    ↓
User redirected to destination
    ↓
Facebook audience updated

This happens in milliseconds. Your audience grows with every click.

Prerequisites

A jo4 account (free tier works)
A Meta Pixel ID from Facebook Business Manager

Step 1: Get Your Meta Pixel ID

Go to Facebook Events Manager
Select your pixel (or create one)
Copy the 15-16 digit Pixel ID

It looks like: 123456789012345

Step 2: Add Pixel to Your Link

When creating or editing a link in jo4:

Expand the Retargeting section
Paste your Pixel ID in the Meta Pixel ID field
Save the link

That's it. Every click on this link now fires your pixel.

Step 3: Verify It's Working

Use the Meta Pixel Helper Chrome extension:

Install the extension
Click your jo4 short link
Check the extension icon - it should show a green checkmark

You'll see:

PageView event fired
Your Pixel ID in the details

Advanced: Track Multiple Pixels

Need different pixels for different campaigns? Each jo4 link can have its own pixel ID. Create separate links for:

Different ad accounts
Different clients
A/B testing audiences

Advanced: Combine with UTM Parameters

jo4 passes UTM parameters through to your destination. Combine with pixel tracking for full attribution:

jo4.io/abc123 (with Meta Pixel + UTMs)
    ↓
Pixel fires with PageView
    ↓
User lands on destination.com/?utm_source=facebook&utm_campaign=spring_sale

Now you have:

Facebook audience data (for retargeting)
UTM tracking (for conversion attribution)

What Events Are Tracked?

Currently, jo4 fires a PageView event on every link click. This is what you need for:

Building Custom Audiences ("People who clicked my links")
Retargeting campaigns
Lookalike audience creation

For Purchase, Lead, or other conversion events, those fire on your destination site where the action happens.

Cost Comparison

Solution	Cost	Complexity
Add pixel to destination	$0	Need site access
Third-party redirect service	$50-200/mo	Medium
jo4 retargeting	$0-16/mo	Low

Most link shorteners charge extra for retargeting features. With jo4, it's included in every plan including free.

Common Pitfalls

Wrong Pixel ID format: Make sure you're using the numeric Pixel ID, not the Pixel Name or Business Manager ID.

Ad blockers: Some users run ad blockers that prevent pixels from firing. This is normal - your tracked audience will be slightly smaller than total clicks.

Pixel not verified: Facebook requires domain verification for some features. The pixel will still fire for building audiences even without verification.

Result

After setup, your Facebook audience grows automatically with every link click. No code changes to destination sites. No complex integrations.

Check Events Manager after a few clicks - you'll see the PageView events with your short link URL.

Already using Meta Pixel with short links? Share your setup in the comments!

jo4.io - URL shortener with built-in retargeting pixels for marketers who track everything.

iOS App Store Screenshots and Compliance: The Gotchas After Your Build Succeeds

Anand Rathnas — Sat, 16 May 2026 01:36:05 +0000

Your EAS build succeeded. The IPA uploaded to App Store Connect. Time to submit for review, right?

Click. "Unable to Add for Review."

The Problem

App Store Connect has requirements that have nothing to do with your code. Screenshots need exact dimensions. Export compliance needs declarations for every country. Privacy questionnaires want to know about every SDK you use.

Here's everything that blocked my submission and how I fixed it.

Part 1: Screenshot Dimensions

I ran the simulator, took screenshots, uploaded them. Error:

Screenshots must be 1284 x 2778 pixels
Uploaded: 1320 x 2868 pixels

iPhone 16 Pro Max uses different dimensions than what App Store Connect expects for the "6.5-inch display" category.

The fix:

# Resize all iPhone screenshots to App Store requirements
for f in ./assets/appstore/iphone/*.png; do
  sips -z 2778 1284 "$f"
done

sips is macOS's built-in image processing tool. The -z flag resizes to exact dimensions.

Part 2: iPad Screenshots - The Stretching Disaster

"Easy," I thought. "Just resize the phone screenshots for iPad."

# DON'T DO THIS
sips -z 2732 2048 phone-screenshot.png --out ipad-screenshot.png

The result looked like someone grabbed my UI and pulled it sideways. Buttons were ovals. Text was bloated. Everything was wrong.

The actual fix:

Boot an actual iPad simulator and take native screenshots:

# Start the iPad simulator
xcrun simctl boot "iPad Pro 13-inch (M4)"

# Build and run on iPad
npx expo run:ios --device "iPad Pro 13-inch (M4)"

# Take screenshots at native resolution
xcrun simctl io booted screenshot ./assets/appstore/ipad/screenshot01.png

Phone and tablet are different form factors. The UI adapts. Resizing just stretches.

Part 3: The Screenshot Content Problem

Now I had the right dimensions. But my app requires login. Screenshots of a login screen aren't compelling.

The solution: Onboarding carousel with demo data.

I created a branch (ft/screenshots) with:

An OnboardingCarousel component showing app features
Hardcoded demo data (fake URLs, fake analytics)
A flag to show this instead of the login screen

// Check if we're in "demo mode" for screenshots
if (isDemoMode) {
  return <OnboardingCarousel />;
}

The carousel showed:

"Shorten Any URL" with a mock input and result
"Track Every Click" with demo analytics charts
"Share From Anywhere" showing the iOS share sheet integration
"Generate QR Codes" with a sample QR code

Took screenshots of each carousel page. Stashed the changes. Real users never see it.

Part 4: Export Compliance - The France Question

Uploaded screenshots. Hit submit. New blocker:

Missing Compliance: Export Compliance Information Required

The form asks about encryption. My app uses HTTPS. Does that count?

Then it asks specifically about France:

The options mention DES, triple-DES, RC4... algorithms I'm not using.

The correct answer: "None of the algorithms mentioned above"

If your app only uses HTTPS (TLS) through iOS's built-in networking, you select that it uses encryption, but then confirm you're only using standard iOS APIs. No custom cryptographic implementations = no export restrictions beyond what Apple already handles.

Part 5: Privacy Declarations

App Store Connect wants to know every piece of data your app collects. For each data type, you specify:

Is it linked to the user's identity?
Is it used for tracking?

My app uses Auth0 and Sentry. Here's what I declared:

Auth0:

Email Address: Linked to identity, not for tracking
Name: Linked to identity, not for tracking
User ID: Linked to identity, not for tracking

Sentry (crash reporting):

Crash Data: Not linked to identity, not for tracking
Performance Data: Not linked to identity, not for tracking

The gotcha: If you use analytics, you need to declare it. If you use third-party login, you're collecting identity data. Be honest - Apple reviews this.

The Complete Screenshot Workflow

For anyone doing this in the future:

Step 1: Capture iPhone Screenshots

# Boot iPhone 15 Pro Max (or similar 6.5" device)
xcrun simctl boot "iPhone 15 Pro Max"

# Run your app
npx expo run:ios --device "iPhone 15 Pro Max"

# Navigate to each screen and capture
xcrun simctl io booted screenshot ./assets/appstore/iphone/screenshot01.png

Step 2: Resize to App Store Dimensions

# iPhone 6.5" requires 1284 x 2778
for f in ./assets/appstore/iphone/*.png; do
  sips -z 2778 1284 "$f"
done

Step 3: Capture iPad Screenshots Separately

# Boot iPad Pro 13"
xcrun simctl boot "iPad Pro 13-inch (M4)"

# Run your app on iPad
npx expo run:ios --device "iPad Pro 13-inch (M4)"

# Capture at native resolution (2048 x 2732)
xcrun simctl io booted screenshot ./assets/appstore/ipad/screenshot01.png

Step 4: Compliance Declarations

Export Compliance: Standard iOS HTTPS = no additional export requirements
Privacy: Declare Auth0 data as identity-linked, crash reporting as not linked

Lessons Learned

Don't resize across form factors. Phone screenshots stretched to iPad dimensions look terrible. Capture natively on each device type.
Create demo content for screenshots. Login screens don't sell apps. Build an onboarding flow or demo mode, capture screenshots, then remove it.
Export compliance isn't scary. If you're using standard iOS networking (URLSession, Alamofire, etc.), you're just using Apple's TLS implementation. Select the exemption options.
Privacy declarations require honesty. List every SDK that touches user data. Auth0, Sentry, analytics - all of it.
sips is your friend. Built into macOS, handles resizing without installing ImageMagick or Photoshop.

Submitting your first iOS app? What unexpected blockers did you hit? Drop them in the comments.

Building jo4.io - URL shortener with a mobile app that survived App Store review.

One Push, Two App Stores: Parallel iOS and Android Builds with GitHub Actions

Anand Rathnas — Thu, 14 May 2026 01:39:58 +0000

Liquid syntax error: Unknown tag 'endraw'