DEV Community: Onkar Deokate

The car wash that comes to the car

Onkar Deokate — Sun, 11 Oct 2026 03:30:00 +0000

Here's a quiet truth about parking: the car just sits there. Two hours, four hours, a whole working day, doing nothing.

What if, while it sits, someone washes it?

That's the last role in ParkEase. A driver books a wash for the car they've just parked, and a local car washer comes to it. Yesterday you saw how ParkEase decides which washer gets the job when three of them tap at once. Today, the washer's side.

Four things you can do as a car washer (the video is thirty seconds)

1. Set your own menu.
Basic exterior, premium, full detailing: switch on the washes you offer, and set a car price and a bike price for each, plus how long it takes. Your menu, your prices.

2. Go online, and jobs come to you.
Flip one switch and nearby wash jobs appear, each with what you'll earn, how far away the car is, and how long the wash takes. A countdown shows how long the offer stays open.

3. Before and after photos.
Accept a job and it's yours. A before photo unlocks Start washing; an after photo finishes the job. No photo, no wash, so a driver always has proof of the car's condition on both sides.

4. Every wash, line by line.
Your earnings show each completed wash: the service price, the ParkEase fee, and what you earned. If a wash was cancelled after you accepted it, the take-back is listed too, not hidden in a total.

That's the whole washer app today.

And that's the cast

Four roles, four apps in one: the owner with an empty parking spot, the driver circling the block, the valet who parks for you, and the washer who cleans the car while it waits. Every one of them was filmed from the real app, not mocked up in a design tool.

Next: everything so far ends with "what you earned". But earned isn't paid. The next update is the moment money actually leaves ParkEase and lands in an owner's bank account, and every way that can go wrong in between. Follow the series. Launch is close.

ParkEase is a peer-to-peer parking marketplace for India, launching soon on Android.
Music: ende.app (CC BY 4.0)

Three washers. One job. Zero locks.

Onkar Deokate — Sat, 10 Oct 2026 03:30:00 +0000

A driver parks, opens ParkEase and books a car wash. The job goes out to up to three nearby washers at once, because the first one might be on a break and the driver shouldn't wait.

All three see it. All three tap Accept.

Exactly one of them can have it. The other two need to hear "this one's gone, more coming," not an error page, not a silent spinner, and definitely not a second washer turning up at the same car.

Yesterday I promised there isn't a single lock in the code. There isn't. Here's what there is.

The WHERE clause is the lock

The usual answers are SELECT … FOR UPDATE, an advisory lock, or a retry loop. ParkEase uses none of them. The accept is one UPDATE, and its WHERE clause only matches a job that is still on offer and still has no washer:

.where(
  and(
    eq(washJobs.id, input.jobId),
    eq(washJobs.status, 'offered'),
    isNull(washJobs.washerUserId),
  ),
)
.returning();

const accepted = updated[0];
if (accepted === undefined) throw new WashJobAlreadyTakenError();

Postgres serialises updates to the same row. The first accept flips the job to accepted. By the time the second and third get their turn, the row no longer matches, so they update zero rows. Zero rows becomes a 409 with copy a washer can read: This job was taken by another partner. More jobs coming!

It's the same move as the booking system earlier in this series: don't arrange for the race not to happen. Let the database answer it.

One more thing is deliberately missing from that transaction: the payment gateway. Creating the payment order inside the accept would mean the two losers each left an orphan order at the gateway that no webhook would ever match. So the order is created later, by the driver's own pay action.

No photo, no wash. The database agrees.

A wash can't start without a before photo, and can't finish without an after photo. The app greys out the buttons, but the app isn't the guard. The row is:

ADD CONSTRAINT wash_jobs_photo_gate_check
CHECK ((status <> 'washing'   OR before_photo_id IS NOT NULL)
AND (status <> 'completed' OR (before_photo_id IS NOT NULL
AND after_photo_id IS NOT NULL)));

No code path, admin tool or future bug can produce a completed wash with no evidence it happened. The command checks the same rule first, purely to turn a constraint name into a sentence a washer can act on:

if (input.event === 'start_washing' && job.beforePhotoId === null) {
  throw new BeforePhotoRequiredError();

Proven over real HTTP

The integration suite runs the real API against a real Postgres in a throwaway container. Three washers accept the same job and the statuses come back [200, 409, 409]. A retried accept with the same idempotency key replays the original answer instead of racing itself. The photo gates refuse in both directions. 84 tests, all passing.

One honest detail: the three accepts in that test run one after another, not truly in parallel. That's on purpose. The test harness shares its "who am I" state between requests, so a parallel version would pass for the wrong reason. The race being proven lives in the database's WHERE clause, and each accept still meets a row the previous one already moved.

What I'd tell myself before starting

Every time I've reached for a lock, the database already had a better one: a constraint, an exclusion, a WHERE. Write the invariant where nothing can route around it.

Tomorrow: the last role video. What a car washer actually does in ParkEase: their own menu, jobs that come to them, and the two photos that bookend every wash. Follow the series.

ParkEase is a peer-to-peer parking marketplace for India, built solo and launching soon on Android.
Code: https://github.com/Deonkar/parkease · Music: ende.app (CC BY 4.0)

Hand over the keys. Get the car back.

Onkar Deokate — Fri, 09 Oct 2026 03:30:00 +0000

Some drivers don't want to find parking at all. They want to pull up at the door, hand over the keys, and walk into the restaurant. In most Indian cities that's a hotel or wedding-hall luxury.

ParkEase makes it a job anyone verified can do. Yesterday you saw what happens when a valet's phone loses signal. Today: what the valet actually does.

Four things you can do as a valet (the video is thirty seconds)

1. See the job before you touch the car.
Every job shows the pickup address and exactly what you'll earn for it. No guessing, no negotiating at the kerb.

2. One tap per step.
I'm on the way. I've arrived. Start parking. Each step is one big button, in order, so a valet with a driver waiting never hunts through a menu.

3. No photo, no confirm.
Before a valet can confirm a car is parked, they take a photo of it, parked. The Confirm parked button stays locked until that photo is attached. If anything is ever disputed, there's evidence.

4. See what you've earned.
Every job credited, straight from the same ledger the rest of ParkEase runs on.

A note on the video: the clips come from the web preview. A valet goes online with background location, which only the Android app has. So the preview honestly says "You are offline" at the top of every screen, and you won't see a job offer arrive. The job screens, the photo rule and the earnings are the real app.

The rule nobody notices

Look at step 3 again. The photo isn't optional, and it isn't a suggestion. It's a lock on the button. That's a pattern you'll see again tomorrow, taken one step further: down into the database itself.

Tomorrow: the last role, and a race. A driver books a car wash. The job goes out to three nearby washers at once. All three tap Accept in the same second. Only one can win, and there isn't a single lock in the code. Tomorrow, how. Follow the series.

ParkEase is a peer-to-peer parking marketplace for India, launching soon on Android.
Music: ende.app (CC BY 4.0)

The signal dropped. Mid-trip. With your car.

Onkar Deokate — Thu, 08 Oct 2026 03:30:00 +0000

You've handed your car keys to a stranger. That's what a valet is. They drive off to park it, and the only thing between you and mild panic is a dot on a map, moving.

Then the valet drives into a basement. Or under a flyover. Or into one of the many parts of Bangalore where 4G just... isn't.

The dot stops.

Yesterday I asked what happens next. Here's the answer, and it's the most careful forty lines in the whole app.

Why the obvious version loses data

The valet app reports a location fix every few seconds, from a background task. The obvious code is: on each fix, send it to the server.

That works right up until the send fails. The background task runs in a headless context where the connection may not even be up. A fire-and-forget send from there doesn't throw anywhere you can see. The fix is just gone, and the route on the driver's map has a hole in it exactly where they were most worried.

Saved first, sent second

So nothing is ever sent before it's stored. Every fix goes into a small on-phone queue, and then the queue tries to drain:

async enqueue(fix) {
  const queued = ordered([...(await read()), fix]).slice(-maxFixes);
  await write(queued);

It still sends immediately. My first version enqueued and waited, which meant nothing reached the server between going online and going offline, and the valet's "last seen" went stale within a minute. The queue is for when a send fails, not a substitute for trying.

The queue has a ceiling, because a phone in a long tunnel shouldn't fill its storage with coordinates:

/** Roughly 15 minutes at the configured interval. */
export const MAX_QUEUED_FIXES = 200;

Past that, the oldest fixes go and the newest always stay. Where the car is now matters more than where it was a quarter of an hour ago.

Offline waits. Refused is dropped.

Here's the subtle part. A send can fail for two very different reasons:

Offline. Worth trying again. Stop here, keep everything, in order.
Rejected. The server said no: say, a fix for a job this valet isn't assigned to. That will be a no forever. Retrying it would block every good fix queued behind it.

if (result.ok) continue;
// A refused fix is consumed; an unsendable one halts the drain so the
// rest keep their order for the next attempt.
if (result.reason === 'rejected') continue;
break;
}

await write(queued.slice(index));

And when the signal comes back, the backlog replays oldest first, so the driver's map redraws the route in the order it was actually driven:

/** Oldest first, so a drain replays the route in the order it was travelled. */
function ordered(fixes: readonly LocationFix[]): LocationFix[] {
  return [...fixes].sort((a, b) => a.recordedAt - b.recordedAt);

Two more things the queue survives: two drains racing each other (only one runs at a time, or the same backlog gets sent twice), and a corrupted stored value (the queue starts empty instead of crashing a background task nobody is watching).

Ten tests

Every one of those decisions has a test: send on capture, hold on failure, oldest first, the bound, refused-versus-offline, stop at the first unsendable fix, a corrupt store, a single malformed entry. Ten tests, all passing, and none of them need a phone.

What I'd tell myself before starting

"Offline" isn't an error to handle. It's a state the app spends real time in. Design for it first, and the happy path falls out for free.

Tomorrow: you've seen what happens in the tunnel. Tomorrow, the valet's side of the screen: taking a job, every step one tap, and the photo of the parked car that has to exist before the job can be confirmed. Follow the series.

ParkEase is a peer-to-peer parking marketplace for India, built solo and launching soon on Android.
Code: https://github.com/Deonkar/parkease · Music: ende.app (CC BY 4.0)

Stop circling the block

Onkar Deokate — Wed, 07 Oct 2026 03:30:00 +0000

You know the loop. Indicator on, crawl past the same shuttered shop, squint at a gap that turns out to be a driveway, go round again. Ten minutes for a space that was probably free the whole time, just behind a gate you didn't know you could use.

ParkEase opens those gates. People with an empty driveway, a basement slot or a society visitor bay rent it out by the hour, and drivers book it before they arrive. Two days ago you met the owners. Yesterday you watched the map break. Today it works, and it's yours.

Five things you can do as a driver (the whole video is thirty seconds)

1. See every free spot around you.
Open the app and the map fills in with real parking spaces near you, each one with its price on the pin. No searching, no guessing which lane has room.

2. Filter for what you need.
Car or bike. Under ₹50 an hour. Covered, CCTV, EV charging, wheelchair access. The map keeps only the spots that fit.

3. See the price before you commit, and why.
Tap a spot and you get today's hourly price, how many slots are free right now, and, when demand is high, a plain label saying so: 1.25x moderate demand. No surprise at checkout.

4. Every rupee, listed. Then your spot is held.
Before you pay you see the whole bill: base price, the demand surcharge, GST, the total. You even see what the owner earns. Tap Hold this spot and it's yours for ten minutes while you pay. Nobody can take it from under you.

5. Walk up with a QR code.
Booked. Your phone shows a QR code. The owner scans it at the gate, you park, done.

That's the whole driver app today: find, check, hold, park.

The part nobody sees

Step 4 has a promise hidden in it: nobody can take it from under you. Two drivers, one last slot, both tapping Hold in the same second. Exactly one of them gets it, every time, and that's enforced by the database itself (I wrote that one up earlier in the series).

Tomorrow: a new role, and a harder problem. Some drivers don't want to park at all. They want to hand over the keys at the door. That means a valet: a stranger driving your car, with the app reporting where it is and a photo when it is parked. What happens when the valet's phone loses signal halfway? Tomorrow, the engineering. Follow the series.

ParkEase is a peer-to-peer parking marketplace for India, launching soon on Android.
Map: © OpenStreetMap contributors · Music: ende.app (CC BY 4.0)

The map was blank. Every test was green.

Onkar Deokate — Tue, 06 Oct 2026 03:30:00 +0000

The most important screen in a parking app is the map. It's the first thing a driver sees, and the only reason they opened the app.

On the web build of ParkEase, that map was blank.

No crash. No red error box. No failing test. Just an empty rectangle where Bangalore should have been, sitting quietly above a perfectly working list of parking spots. Every test passed, because no test looked at the map.

Yesterday I promised you the story. Here it is: three bugs, stacked so neatly that fixing one only revealed the next.

Bug one: the worker that was a web page

MapLibre, the open-source map renderer ParkEase uses, does its heavy lifting in a Web Worker. To find that worker's file, MapLibre 6 builds a URL relative to its own module.

Under Expo's web bundler there is no "own module". There's one big bundle. So the URL pointed at a file that didn't exist, and the dev server did what dev servers do with unknown paths: it served the app's HTML page.

MapLibre asked for JavaScript, got HTML, and the worker died before processing a single tile. Nothing on screen said so.

The fix is to tell MapLibre exactly where its worker lives, and to make sure it's really there:

export const MAPLIBRE_WORKER_URL = '/maplibre/maplibre-gl-worker.mjs';

try {
// Before any Map is created: MapLibre spawns its workers on the first one.
(candidate as WebMapModule).setWorkerUrl(MAPLIBRE_WORKER_URL);

A postinstall script copies the worker, and every chunk it imports, into the folder the web build serves. It follows the worker's own imports instead of a hard-coded file list, so a future MapLibre release that splits out another chunk gets copied too. If the copy fails, the install fails, loudly, and names the web map. A silent copy failure is how this whole story started.

Bug two: the box with no height

Workers fixed. Tiles loading. Map... still blank.

The CSS ParkMap injects (the app doesn't load MapLibre's own stylesheet) had one extra rule: overflow: hidden on the canvas container. That container only holds absolutely positioned children, so it has zero height. Clip a zero-height box and you clip everything inside it: the canvas and every marker.

The fix was deleting a line. The test that keeps it deleted:

it('never clips the map canvas container', () => {
  for (const body of rules(MAPLIBRE_CSS, '.maplibregl-canvas-container')) {
    expect(body).not.toMatch(/overflow\s*:\s*hidden/);
  }
});

Bug three: every spot in one corner

This is my favourite, because the map came back. Streets, parks, the blue dot where you're standing. And in the top-left corner, one lonely price tag: ₹20.

I counted the marker elements: twenty, all with the same coordinates.

Here's why. MapLibre places each marker by writing a transform onto the marker element, something like translate(412px, 318px). Our entrance animation, a gentle scale-and-rise as spots appear, also animated transform. A CSS animation beats an inline style, so every marker's position was overwritten with scale(1) translateY(0). Which, as positions go, is the top-left corner.

The fix keeps the exact same animation and moves it onto the individual scale and translate properties. Those compose with transform instead of replacing it:

`@keyframes parkease-marker-in{from{opacity:0;scale:0.6;translate:0 6px}to{opacity:1;scale:1;translate:0 0}}`,

And the test that will catch the next person (probably me) who reaches for transform:

it('never animates transform on the marker element MapLibre positions', () => {
  expect(keyframes(MAPLIBRE_CSS, 'parkease-marker-in')).not.toMatch(/(^|[{;])\s*transform\s*:/);
});

Ten tests now guard the map: three on the CSS, four on how the map starts (including that it shows a real "map unavailable" state with the reason, instead of a blank box, when the worker can't be set up), and three on the worker copy.

A note on the video: the "before" frames were reproduced on the fixed build by putting the old behaviour back: the worker request answered with the HTML page, and the old CSS rules re-injected. The broken states are real; they're just recreated rather than recorded at the time.

What I'd tell myself before starting

A test suite proves the things you thought to check. A blank screen isn't an error, so nothing failed. Now the rule is simple: if a screen can be empty, the empty state has to say why.

Tomorrow: you've seen the map break. Tomorrow you see what it's for. Open the app as a driver, find a free spot three streets away, see exactly what it costs and why, and walk up to the gate with a QR code in your hand. Five steps. Thirty seconds. Follow the series so you don't miss it.

ParkEase is a peer-to-peer parking marketplace for India, built solo and launching soon on Android.
Code: https://github.com/Deonkar/parkease · Map: © OpenStreetMap contributors · Music: ende.app (CC BY 4.0)

Your empty parking spot just got a job

Onkar Deokate — Fri, 02 Oct 2026 13:30:00 +0000

Somewhere in Bangalore right now there's a driveway with nothing in it. A basement slot that sits empty from nine to six. A space someone pays for and never uses.

And three streets away, a driver is circling the same block for the fourth time.

ParkEase puts those two people together. Yesterday I showed you the ledger underneath. Today, the part that matters: what it's like to be the owner.

Five things you can do (the whole video is under thirty seconds)

1. List your space in five quick steps.
Where it is, what it's called, how many cars and bikes fit, your price, when it's available. Submit, and your listing waits for approval before it goes live.

2. Set your own price.
Per hour, per slot, separately for cars and for two-wheelers. Your spot, your number.

3. Check drivers in with one scan.
When a driver arrives they show a QR code. You scan it, and your phone confirms who it is, their vehicle number and their booked time. No paper, no guessing, no "I booked, I promise."

4. See every booking, line by line.
Every booking shows three lines: the price, the ParkEase fee, and exactly what you earned. No mystery deductions. (Yesterday's post is the story of why that line is harder to get right than it looks.)

5. Watch it add up.
Today's earnings, this week's, with a chart that fills in as the week goes.

That's the whole owner app today. It's small on purpose.

What I'm not telling you yet

Everything above happens on the owner's phone. The other half of ParkEase is a driver looking at a map of free spots nearby.

For a while, on the web build, that map was empty. No error on screen. Every test green. Just a blank box where Bangalore should be. And when the map finally came back, every parking spot on it was piled into the top-left corner.

Tomorrow: we cross to the other side of the gate. The driver's map: why it was blank, and the single CSS animation that stacked twenty-one parking spots in one corner. Follow the series. Launch is closer than you think.

ParkEase is a peer-to-peer parking marketplace for India, launching soon on Android.
Music: ende.app (CC BY 4.0)

One booking. Three answers. Only one was true.

Onkar Deokate — Thu, 01 Oct 2026 13:30:00 +0000

A parking space owner opens their app and sees ₹82.47.

They tap Earnings. It says ₹51.00.

Payday comes. ₹42.50 lands.

Same booking. Same owner. Three different numbers, and every one of them came from code that looked correct.

That was version one of ParkEase, the peer-to-peer parking marketplace I'm building for India. People with an empty driveway or basement slot list it; drivers find it on a map and book it by the hour. And we're close to launch. Close enough that "which number is real?" had to become a question the app can't even ask.

This is how.

Three careful people, three wrong answers

Nobody wrote a bug on purpose. Three parts of the app each answered "how much did this owner earn?":

The dashboard took 85% of the booking total.
The earnings screen summed the owner's account in the ledger.
The payout job subtracted a recomputed fee from the base price.

Each formula is locally reasonable. Put a surged booking through all three and they split three ways. The dashboard counted surge as the owner's money (it isn't), and the payout job lost the surge allocation entirely.

Only one of them was reading the truth: the ledger. So the fix wasn't a fourth formula. It was deleting two.

Every figure is one query

Now there is one question, asked one way. Owed, today, this month, last month: all four are the same function over the ledger, scoped to a different period:

async forOwner(ownerId: string): Promise<OwnerDashboardData> {
  return this.db.transaction(
    async (tx) => {
      // …
      const owed = await this.balance.movement(ownerId, undefined, tx);
      const today = await this.balance.movement(ownerId, periodBound(at, 'today'), tx);
      const month = await this.balance.movement(ownerId, periodBound(at, 'month'), tx);
      const lastMonth = await this.balance.movement(ownerId, lastMonthToDate(at), tx);
      // …
    },
    { isolationLevel: 'repeatable read', accessMode: 'read only' },
  );
}

And movement() is nothing clever. It's a sum over the owner's side of a double-entry ledger, in integer paise, so there is no floating point anywhere near money:

const CREDITS = sql<string>`coalesce(sum(${ledgerEntries.amountPaise})
  filter (where ${ledgerEntries.direction} = 'credit'), 0)::text`;
const DEBITS = sql<string>`coalesce(sum(${ledgerEntries.amountPaise})
  filter (where ${ledgerEntries.direction} = 'debit'), 0)::text`;

async movement(
  ownerId: string,
  bound: SQL | undefined,
  reader: Reader = this.db,
): Promise<Movement> {
  const [row] = await reader
    .select({ creditsPaise: CREDITS, debitsPaise: DEBITS })
    .from(ledgerEntries)
    .innerJoin(bookings, eq(bookings.id, ledgerEntries.bookingId))
    .innerJoin(spaces, eq(spaces.id, bookings.spaceId))
    .where(and(this.ownerScope(ownerId), bound));

  const creditsPaise = Number(row?.creditsPaise ?? 0);
  const debitsPaise = Number(row?.debitsPaise ?? 0);
  return { creditsPaise, debitsPaise, netPaise: net(debitsPaise, creditsPaise) };
}

The detail that's easy to miss

Look at the last line of that transaction: repeatable read, read only.

Those four movement() calls are four separate SELECTs. Without one snapshot, a booking that settles between the "today" read and the "month" read could make today bigger than this month for one page load. Rare? Yes. The kind of thing an owner screenshots and sends to support? Also yes. One read-only snapshot means all four numbers see the same instant.

Surge never touches the owner's line

The platform takes one fee: 15% of the base price plus all of the surge. So an owner's earnings are always base minus 15%, whatever demand did that evening. The rate lives in exactly one dated table:

export const PLATFORM_COMMISSION_RATE_HISTORY: readonly DatedRate[] = [
  {
    rate: toRate(0.15),
    effectiveFrom: '2026-01-01',
    note: 'Launch rate. 15% of base, charged once, deducted from the owner payout.',
  },
];

Don't trust me. Trust the test.

"They use the same function" is a claim. This test turns it into a fact. It goes through the real HTTP stack, against a real Postgres in a throwaway container, books twice, and asks both screens:

it('dashboard and earnings agree on owner earnings', async () => {
  const spaceId = await seedSpace(h, { lat: 12.9345, lng: 77.6266, carSlots: 2 });
  await bookConfirmed(spaceId, 2);
  await bookConfirmed(spaceId, 6);

  const dashboard = (await get('/owner/dashboard')).body as {
    data: { month: { netPaise: number }; owedPaise: number; statement: unknown[] };
  };
  const earnings = (await get('/owner/earnings?period=month')).body as {
    data: { netPaise: number; bookings: number };
  };

  expect(dashboard.data.month.netPaise).toBe(earnings.data.netPaise);
  expect(dashboard.data.owedPaise).toBe(earnings.data.netPaise);
  expect(earnings.data.bookings).toBe(2);
  expect(dashboard.data.statement).toHaveLength(2);
});

All 10 tests in that file pass. One of them pins the other half of the rule: a surged booking shows the owner base, fee and net, with no surge, no GST and no booking total.

The lesson I paid for

If a user can put two numbers side by side, they must come from the same function. Not the same formula, copied carefully. The same function.

Tomorrow: you've seen the machinery. Tomorrow you see what it's for: what a parking space owner actually does in ParkEase, from an empty driveway to a driver pulling up at the gate and the moment their phone says checked in. Five things. Under thirty seconds. Follow the series so you don't miss it.

ParkEase is a peer-to-peer parking marketplace for India, built solo and launching soon on Android.
Code: https://github.com/Deonkar/parkease · Music: ende.app (CC BY 4.0)

72 commits, 42 decisions, 6 hidden bugs: building a React Native partner app with Claude as a team, not a tool

Onkar Deokate — Wed, 30 Sep 2026 13:30:00 +0000

I'm building ParkEase, a peer-to-peer parking marketplace for India: drivers, space owners, valets, car-wash partners and admins, spread across a NestJS API, a worker, an Expo React Native app, an admin panel and a marketing site. Task 14 was the car-wash partner app. That's the screen a washer lives in all day: receive offers, take before and after photos, edit a price menu, check earnings.

I built it with Claude Code, and "built with AI" undersells how it actually worked. The task ended as 72 commits, about 22,800 added lines across 185 files, 1,013 mobile tests, 397 integration tests against real Postgres, 42 recorded decisions, and six defects that had been sitting in already-merged code. It also took far longer than it should have, and some of the mistakes were the AI's own. Here's all of it.

The setup: `/flow`, gates, and a paper trail

The core of my workflow is a skill I call /flow. It isn't a prompt. It's a routing layer that knows my project: the architecture decision records (ADRs), the coding rules, the task files, and which of about 80 skills and 25 specialist subagents apply at each phase. Every phase has a gate:

Phase	Gate
Think	`brainstorming`: no code until I approve a design
Direction (UI only)	2–3 rendered visual directions; I pick
Plan	`writing-plans`: bite-sized TDD tasks
Build	`test-driven-development`: see it fail first
Review	a stack of lenses, never one reviewer
Design audit	three design lenses, because a code review is not a design review
Verify	evidence before any "done"
Ship	an 18-line pre-PR gate, pasted into the PR

Two rules in /flow did the most work on this task.

"The governance chain is read from the docs, never inferred." My ADRs override my rules, which override the PRD. When a skill's advice contradicts an ADR, the ADR wins, and Claude has to say so out loud. It came up in the first ten minutes. The UI/UX skill's generator recommended orange with a gaming display font for a car-wash app. The project's palette ADR says cobalt and availability-green, and "brand orange" had already been rejected once, so Claude rejected the suggestion and cited the ADR.

"An agent never satisfies a gate." Subagents do bounded work inside a gate. The gate takes the approval, and the gate checks the result. It's the difference between five green agent reports and a feature that works.

What went well

1. Choosing a direction from pictures, not paragraphs

Before a single screen existed, Claude rendered three directions as tappable mockups on a design canvas. Worklist was dense and literal. Bay made money the headline and turned the photo pair into one object. Docket used a work-ticket metaphor. I picked Bay.

The reasoning behind Bay was genuinely good product thinking. The task file drew the before/after photo gate as an alert card that appears when a transition is already blocked. Bay makes the pair a persistent two-slot frame from the moment a job is accepted, so the gate becomes a standing obligation instead of an interruption. I wouldn't have asked for that. A good designer brings the idea you didn't ask for.

2. Review as a stack found bugs that were already in `main`

Every task got a spec-plus-quality review and a fix loop. Then the whole branch went through seven specialist lenses, run three at a time: security, silent failures, database, TypeScript, React, test adequacy and spec conformance. Here are six things they, and the live walkthrough, surfaced in code that was already merged:

The valet proof-photo upload had never worked. The mobile client posted multipart/form-data; the API parsed { proofPhotoId: string }. Every call returned a 400. The component test injected the broken dependency, so the test couldn't see it.
The driver's wash screen failed for every real partner. It read users.name into a non-null schema, and nothing in the codebase ever writes users.name.
A business partner could never be verified. Only the ID-document endpoint set pending, and the business form doesn't collect an ID.
Valet and washer partners opened the app to "Unmatched Route". The redirect built /(role), and those two route groups had no index.tsx.
The idempotency layer's store/release calls were fire-and-forget. A failed write left a key locked for 24 hours.
An unregistered partner got a 404 with the error code ERROR, not NOT_FOUND. The client couldn't tell "you haven't signed up yet" apart from "the server broke", so it had no way to route to registration.

None of these was a style nit. Each one would have broken a real user.

3. A ledger of every decision taken on my behalf

The execution skill has a rule I've come to love: rulings, not stalls. When a plan is ambiguous or wrong, the agent decides, and records it:

Ruling: T6-R1 — a pending washer's offers state is "online switch locked with
the reason", not "offers visible, Accept locked". The server makes the task
file's version unreachable (set-availability.command.ts:43 refuses isOnline
unless verified). — Cost if wrong: a pending-preview feed would be a server
change in task 13's dispatch.

By the end there were 42 of these, and every one went into the PR body as a table: decision, reason, cost if wrong. That's the part I actually review. It turns "the AI did stuff" into decisions I can overrule.

4. It opened the app, and that found what tests can't

The UI gate says a screen isn't done until it has been opened at mobile and desktop widths. Claude drove the web preview and measured things:

tab labels were 12px text in a 9px box, so they were clipped;
at a short viewport, the empty-state illustration covered the online toggle and pushed the only button under the tab bar;
the switch's "on" colour was react-native-web's default #009688, not a design token;
green, which the design system reserves for "available right now", was being used for "done".

A mechanical design detector, run as a separate isolated pass, independently flagged the same occlusion. The design review scored the screens 23/40. Every issue was fixed and re-checked live afterwards.

What went badly

1. The AI's own plan had bugs, and reviews caught them late

I want to be honest about this, because the "AI writes perfect code" crowd isn't.

The plan's upload step sent no idempotency key, so every upload would have failed as "check your connection".
The fix for that was then wrong in the other direction. Reusing the key across retries meant the server replayed a stale Cloudinary signature for 24 hours, and Cloudinary rejects signatures older than an hour. That became an ADR: an idempotency key belongs to a side effect, not to an HTTP call.
The earnings query's correlated subquery rendered as:

  where "txn_id" = "txn_id"   -- always true

Every earnings line summed every posting in the ledger. It passed two reviews, because every test fixture had exactly one job. A later reviewer caught it with a two-job test.

A plan test asserted rupeesToPaise('0.07') → 7, which contradicts its own ₹10 minimum. The justification for it ("319.20 * 100 is a float error") was false; in Node it's exactly 31920. The implementer stopped, flagged the contradiction, and didn't bend the test. That's exactly what you want.

The lesson isn't "AI is sloppy". It's that a plan is a hypothesis, and the review stack is what tests it.

2. Fixes introduced regressions

Two fixes from the final fix wave broke something new, and both were caught by the scoped re-review:

memoising the offer card made a recycled FlashList cell carry an "expired" flag onto a live offer;
a stale-lock takeover meant a committed-but-unstored request could run twice (think "second payment order").

Both were fixed before merge. It's also a reminder that "the review passed" is only as good as the review of the fix.

3. Wall-clock time, mostly rate limits

The work itself wasn't the slow part. Agents were cut off by session and weekly rate limits more than five times, mid-task. The Sonnet weekly quota, which the implementer and reviewer subagents were running on, ran out on day one. From then on, subagents ran on Opus for anything needing judgment and Haiku for pure transcription. The design of the process saved it: every agent writes its report to disk, every task has a ledger line, and an interrupted agent is resumed with its context intact instead of restarted. Nothing was redone, but the calendar time still stretched across two days.

4. The environment lied, and it nearly cost a false bug hunt

At one point the camera sheet's shutter measured at y=1564 in an 812px viewport, which looked like a serious layout bug. It wasn't. The browser pane was hidden, so requestAnimationFrame was firing zero times a second, and the slide-in animation never ran. Claude measured frames per second before diagnosing, and that check is now a documented learning.

Similarly, the web preview wouldn't start because Metro was crawling 1.6 GB of stale git worktrees. The fix was a blockList in metro.config.js, not deleting my files, which Claude refused to do without asking. When I did ask, it first showed me which worktrees held uncommitted work.

How Opus 5.5 helped

The main session, the "controller" that plans, dispatches and adjudicates, started on Opus 5 and moved to Opus 5.5 early in the task. Everything from the implementation onward ran on it: orchestration, the final seven-lens review, and every ruling. What stood out wasn't raw coding speed. It was judgment in the controller seat:

It said when its own plan was wrong. "The defect is in MY plan's Step 4 code, not the implementer's transcription" is a sentence I saw more than once, followed by a ruling and a fix.
It verified before it asserted. Before acting on a reviewer's "Critical", it re-read the code. It confirmed set-availability.command.ts:43 before overruling a line in the task file, and it confirmed errorCodeFor returns 'ERROR' for a bare NotFoundException before changing the server.
It held the line on destructive actions. It deleted no worktree with uncommitted work until I chose. It didn't edit my CLAUDE.md because a subagent suggested it. It didn't open the PR until the gate was green.
It pushed back on scope in both directions. It proposed extending the earnings API when the task was unbuildable without it, and it refused the sparkline because it would have required money arithmetic in the client.

How AI actually helps (and where it doesn't)

It helps most as a team. Seven reviewers reading the same branch through seven different lenses is something I couldn't staff myself. The database lens found a missing index. The React lens found the recycled-cell bug. The test-adequacy lens found that no test anywhere proved an unverified partner gets refused, the single highest-risk gap in the branch.

It helps with the tedious truth-telling. Every PR claim comes with pasted output: lint 16/16, typecheck 15/15, 1,013 tests, 397 integration tests, 72 commits scanned by gitleaks with zero leaks. Where the gate wasn't green (pnpm audit has 33 pre-existing findings), the PR says so.

It does not replace a device. The real camera, the real Cloudinary upload, TalkBack on Android and the Maestro end-to-end flows are all explicitly listed in the PR as not verified here. An honest "I couldn't check this" beats a confident green checkmark.

The token-optimisation playbook

Long agentic sessions die from context bloat before they die from bad code. Here's what we did, all of it visible in the session:

Hand artifacts over as files, not pastes. Each implementer gets a task brief extracted from the plan (never the whole plan). Each reviewer gets a precomputed diff package: commit list, stat and full diff in one file. The controller never pastes a diff into a prompt.
Short return contracts. Every subagent writes its full report to disk and returns under 15 lines: status, commits, one-line test summary, concerns. The detail lives in the file, and the controller reads it only when needed.
Tiered models. Haiku for transcription tasks and small scoped re-reviews, and for running the pre-PR gate commands. Opus for money, security, concurrency and design judgment. The rule of thumb: turn count beats token price, so the cheapest model isn't cheap if it takes three times the turns.
Scoped re-reviews. After a fix, the reviewer sees only the fix diff and the findings list, and gives a verdict of ADDRESSED or NOT ADDRESSED per finding. No re-reviewing the world.
Slice big diffs by surface. The final branch diff was 700 KB. It was split into server source, server tests, mobile source and mobile tests, and each lens read only its slice.
Cap the output. "At most 12 findings, severity-ranked, under 600 words, no praise section." Praise is tokens.
Batch lenses three at a time, so a burst of parallel work doesn't blow the rate limit, the one resource we kept running out of.
Resume, don't restart. A rate-limited agent is resumed with its context rather than re-dispatched from scratch. The largest implementer run used around 520k tokens; redoing that would have been the most expensive mistake available.
A ledger as recovery memory. progress.md records every task's status and every ruling. After an interruption, the ledger and git log beat the controller's recollection, and no completed task was ever re-dispatched.
Measure before you investigate. One requestAnimationFrame count replaced what could have been an hour of chasing a phantom layout bug.

Our /flow also has a local knowledge graph of the codebase (tree-sitter, no embeddings) for "what calls what" questions, which saves ten greps with one query. In this task I'll admit we still grepped more than we queried. That's the next habit to build.

The takeaway

The most valuable output of this task wasn't the 22,800 lines. It was six bugs that were already shipped, a 42-row table of decisions I can overrule, and a PR that tells me exactly what it did not verify.

AI didn't make this fast. Rate limits and my own process made sure of that. What it did was make the work inspectable: every claim has evidence, every decision has a cost-if-wrong, and every gap has a row in the backlog. For a solo developer building something that moves real money, I'll take inspectable over fast.

ParkEase is built with Claude Code, Expo SDK 57, NestJS 11 on Fastify, Drizzle, and PostgreSQL 18 + PostGIS. The task 14 PR: https://github.com/Deonkar/parkease/pull/14

Poison Messages in Kafka: Retries, a Dead-Letter Queue, and the Replay Shortcut I'd Fix

Onkar Deokate — Tue, 29 Sep 2026 13:30:00 +0000

TL;DR: One bad message can stop a Kafka consumer, because offsets are committed in order: if record #41 can never be processed, record #42 never gets processed either. In TxFlow I handle this with bounded retries plus exponential backoff, a dead-letter topic, and a DLQ handler that makes failures visible and replayable. This post covers the design, the order of operations that keeps it safe, and the replay shortcut I'd fix before calling it production-ready.

Continuing my TxFlow posts. Earlier: why I moved from SQS to Kafka and making consumers idempotent.

The problem: poison messages

A poison message is a record your consumer will never successfully process: malformed JSON, a missing field, a user that doesn't exist, a currency you don't support.

With SQS or Sidekiq, a failing message just sits in its own retry cycle while everything else keeps flowing. Kafka is different. A consumer group tracks one offset per partition, and committing offset 42 means "everything up to 42 is done". If you can't get past 41, you can't commit, and the partition is stuck. Consumer lag grows, and every user whose events hash to that partition waits.

You can reproduce this in TxFlow with one command:

echo '{bad json' | docker compose exec -T redpanda \
  rpk topic produce payments.initiated -X brokers=redpanda:9092 -k user_999

Step 1: separate "try again" from "never going to work"

Not every failure deserves a retry:

Transient: database timeout, broker hiccup, downstream 503. Retrying often works.
Permanent: can't parse, fails validation, business rule rejects it. Retrying just wastes time while the partition waits.

A simplified sketch of the consumer framework's shape:

MAX_ATTEMPTS = 3

def process_with_retries(msg, handler):
    try:
        event = parse_and_validate(msg.value())
    except ValidationError as e:
        return send_to_dlq(msg, reason="invalid", error=e, attempts=0)  # no retries

    for attempt in range(1, MAX_ATTEMPTS + 1):
        try:
            return handler(event)
        except Exception as e:
            if attempt == MAX_ATTEMPTS:
                return send_to_dlq(msg, reason="exhausted", error=e, attempts=attempt)
            time.sleep(0.2 * 2 ** (attempt - 1))  # 0.2s, 0.4s...

TxFlow retries up to 3 times with exponential backoff, inside the consumer. That's a deliberate trade-off. While a record is being retried, the rest of its partition waits. At demo volume, a second of blocking is fine. At high volume, you'd use retry topics instead (payments.retry.30s, payments.retry.5m, and so on), so the main topic keeps moving while failed records wait their turn somewhere else.

Step 2: a useful DLQ envelope

"Sent to DLQ" is only useful if someone can later work out what failed, where and why. The envelope should carry enough to debug and replay without digging through logs:

{
  "original_topic": "payments.initiated",
  "partition": 2,
  "offset": 41,
  "key": "user_999",
  "consumer_group": "wallet",
  "reason": "exhausted",
  "error": "InsufficientFunds: user_999",
  "attempts": 3,
  "failed_at": "2026-09-29T10:12:03Z",
  "payload": { "...": "original event, untouched" }
}

consumer_group matters most. The same event can be fine for four groups and fail for one. When you replay it, you want only that one group to process it again.

Step 3: order of operations

The sequence that keeps this safe:

Produce the envelope to payments.dlq
Wait for the broker to acknowledge it (flush)
Then commit the original offset

If you commit first and crash before the DLQ write lands, the failure disappears without a trace. If you write to the DLQ first and crash before committing, the worst case is a duplicate DLQ entry. That's easy to dedupe and much easier to live with than a lost failure.

TxFlow's DLQ topic has one partition. DLQ traffic is low, and a single ordered stream is easier to inspect and replay.

Step 4: make failures visible

A DLQ nobody looks at is just a slower way to lose data. TxFlow's dlq-handler service:

consumes payments.dlq,
stores each failure in a dead_letter_events table in Postgres,
exposes GET /dlq for the dashboard, which shows recent failures with search, filters and a Replay button,
sits next to consumer lag per group on the same dashboard, because a growing DLQ and a growing lag are the two signals that something's wrong.

Not everything needs a DLQ

The analytics consumer has no DLQ at all. It increments counters, and if an event can't be counted after retries, it isn't parked anywhere. A DLQ is an operational commitment: someone has to look at it. I only give one to consumers where a skipped event actually costs something (wallet, fraud, notify, audit).

The replay shortcut I'd fix

Today, the dashboard's Replay button sends the payment back through POST /payment. That's fine for a demo, but it's the wrong layer, and it's the first thing on my improvement list:

the API either rejects it (409, if the original idempotency key is reused) or produces a fresh event,
a fresh event gets a new event_id, so it doesn't match any consumer's dedup keys. All five groups process it again, not just the one that failed. A failure in the notify consumer could end up re-running the wallet debit,
the link to the original event is lost, which makes debugging harder.

The better design re-publishes the original event (same event_id, same payload) to a replay or retry topic that only the failed consumer group reads. Every other group's idempotency stays intact, and the audit trail shows it was a replay.

Checklist

If you're adding a DLQ to a Kafka consumer:

Send permanent failures (parsing, validation) straight to the DLQ, without retrying
Keep in-consumer retries few and short, or move to retry topics
Write to the DLQ, wait for the ack, then commit the offset
Put consumer_group, topic/partition/offset, error and attempt count in the envelope
Store DLQ entries somewhere queryable, with a dashboard or alert
Replay to the failed group only, with the original event ID

Question for you: do you use in-consumer retries or retry topics? And what's the strangest poison message you've found in a DLQ?

Money in a Parking App: Paise, Basis Points and a Ledger Postgres Won't Let You Edit

Onkar Deokate — Mon, 28 Sep 2026 13:30:00 +0000

TL;DR: Money in ParkEase is stored as integer paise, rates as basis points, and every rupee movement is written to a double-entry ledger that Postgres refuses to update or delete. This post covers how a price gets calculated and checked twice, and how refunds get split without drifting by one paisa. It also covers why the refund split uses BigInt even though amounts are just rupees.

Part 3 of my series on building ParkEase, a peer-to-peer parking marketplace for India. Earlier parts covered double-booking prevention with exclusion constraints and a pagination bug inside a geo-search cache.

Rule 1: no floats, ever

Every amount is an integer number of paise (₹1 = 100 paise), stored as bigint. Every rate is either a branded Rate type in code or basis points in the database (1.0x surge is stored as 10000).

base_paise           bigint NOT NULL,
surge_premium_paise  bigint NOT NULL DEFAULT 0,
surge_multiplier_bp  integer NOT NULL DEFAULT 10000,
parkease_fee_paise   bigint NOT NULL,
gst_paise            bigint NOT NULL,
total_paise          bigint NOT NULL,
owner_earnings_paise bigint NOT NULL,

The booking stores the whole quote, not just the total. The price a driver agreed to can be rebuilt from the booking row alone, without re-running whatever the rate card said that day.

How a price is built

The model: the owner sets a base price. ParkEase takes a 15% commission from the owner's side. Surge (1.0x–3.0x) adds a premium that goes to the platform. GST at 18% applies only to the ParkEase fee, not to the whole booking.

export function quote(input: FeeInput & { gstRate?: Rate }): Quote {
  const fee = parkEaseFee(input);                    // commission + surge premium
  const gstPaise = mulRate(fee.parkeaseFeePaise, gstRate);

  const ownerEarningsPaise = subPaise(fee.basePaise, fee.commissionPaise);
  const driverTotalPaise   = addPaise(fee.basePaise, fee.surgePremiumPaise, gstPaise);

  const result = { ...fee, gstPaise, driverTotalPaise, ownerEarningsPaise, /* bp fields */ };
  assertQuoteBalances(result);
  return result;
}

A worked example with a ₹100 base price and 1.5x surge:

	paise
Base	10,000
Surge premium (0.5 × base)	5,000
Commission (15% of base)	1,500
ParkEase fee (commission + surge)	6,500
GST (18% of fee)	1,170
Driver pays (base + surge + GST)	16,170
Owner earns (base − commission)	8,500

Check: owner 8,500 + fee 6,500 + GST 1,170 = 16,170. Every paisa the driver pays ends up somewhere specific.

Checked twice: in code and in the database

assertQuoteBalances throws if owner + fee + GST ≠ driver total. The database checks the same thing again:

CONSTRAINT bookings_balance_check
  CHECK (total_paise = base_paise + surge_premium_paise + gst_paise)

It looks redundant, and that's the point. The TypeScript check catches a bad formula in tests. The CHECK catches the code path I haven't written yet: a future admin tool, a data fix, or a migration. Booking extensions add to each money column instead of replacing them, so the constraint keeps holding after an extension too.

Rates have history

Tax rates change, and commission rates will too. So rates are dated lists, not constants:

export const GST_RATE_HISTORY: readonly DatedRate[] = [
  { rate: toRate(0.18), effectiveFrom: '2026-01-01',
    note: '18% on the ParkEase Fee only, not on the booking total.' },
];

export function rateAt(history: readonly DatedRate[], at = new Date()): Rate {
  const applicable = history
    .filter((e) => new Date(`${e.effectiveFrom}T00:00:00+05:30`) <= at) // IST midnight
    .at(-1);
  if (!applicable) throw new RangeError(`No rate in force at ${at.toISOString()}`);
  return applicable.rate;
}

Two small details I like here. The effective date is midnight IST, not UTC, because that's when an Indian rate change actually takes effect. And tax items I haven't confirmed yet (TCS/TDS) are listed at 0% with a note saying they're pending review by a chartered accountant, so the open question is written down in the code itself.

The ledger: double-entry, append-only

Every money movement is a set of ledger_entries that share a txn_id. Each entry is a debit or credit against a named account:

CONSTRAINT ledger_entries_account_check CHECK (account IN (
  'driver_receivable','owner_payable','platform_revenue','gst_payable',
  'tcs_payable','tds_payable','gateway_fees','refunds_payable','promo_expense'
)),
CONSTRAINT ledger_entries_amount_check CHECK (amount_paise > 0),

The ledger service checks that the debits and credits balance before inserting, and it only ever runs inside the caller's transaction:

async post(tx: TxHandle, posting: LedgerPosting): Promise<string> {
  assertEntriesBalance(posting.entries); // fails the whole transaction, naming the bad posting
  const txnId = posting.txnId ?? uuidv7();
  await tx.insert(ledgerEntries).values(posting.entries.map((e) => ({ txnId, ...e })));
  return txnId;
}

An unbalanced posting aborts the business operation that caused it, instead of landing in the table for a nightly check to find. The nightly ledger-balance job still exists as a second check.

"Append-only" enforced by the database

Mistakes in a ledger get fixed with a reversing entry, never an edit. Two layers make sure of that:

CREATE FUNCTION ledger_entries_reject_mutation() RETURNS trigger AS $$
BEGIN
  RAISE EXCEPTION 'ledger_entries is append-only. Post a reversing entry instead of a %', TG_OP
    USING ERRCODE = 'restrict_violation';
END; $$ LANGUAGE plpgsql;

CREATE TRIGGER ledger_entries_no_mutation
  BEFORE UPDATE OR DELETE ON ledger_entries
  FOR EACH ROW EXECUTE FUNCTION ledger_entries_reject_mutation();

REVOKE UPDATE, DELETE, TRUNCATE ON ledger_entries FROM parkease_app;
GRANT SELECT, INSERT ON ledger_entries TO parkease_app;

Why both? The REVOKE stops the application role outright. The trigger catches a privileged session, such as a migration or someone in psql with the owner role. Row-level triggers don't fire on TRUNCATE, which is one reason the REVOKE includes it. A superuser can still disable triggers, so this is a strong guardrail rather than tamper-proofing. It turns "someone edited a ledger row" from a risk you might never notice into something that takes a deliberate action.

Splitting refunds without losing a paisa

A partial refund has to be spread back across the owner's share, the fee and the GST. The obvious approach, mulRate(owner, 0.5) and then the same for the fee and the GST, rounds three times on its own, and three roundings can be off by one paisa in total. In this system, one paisa off means an unbalanced posting, and assertEntriesBalance would reject the whole refund transaction.

So refunds use largest-remainder allocation:

export function allocateProportionally(totalPaise: number, weights: readonly number[]): number[] {
  const divisor = BigInt(weights.reduce((s, w) => s + w, 0));
  const shares = weights.map((w) => {
    const n = BigInt(totalPaise) * BigInt(w);
    return { floor: n / divisor, remainder: n % divisor };
  });

  const parts = shares.map((s) => Number(s.floor));
  let spare = totalPaise - parts.reduce((s, p) => s + p, 0);

  // Hand the leftover paise to the largest remainders; ties go to the lower index.
  const order = shares
    .map((s, index) => ({ index, remainder: s.remainder }))
    .sort((a, b) => (a.remainder === b.remainder ? a.index - b.index : a.remainder > b.remainder ? -1 : 1));

  for (const { index } of order) {
    if (spare === 0) break;
    parts[index] += 1;
    spare -= 1;
  }
  return parts; // always sums to exactly totalPaise
}

Two decisions in there:

Deterministic tie-breaking. A refund recalculated during an incident investigation has to match the one that was actually written.
BigInt for the multiplication. ₹1 crore is 10⁹ paise. Multiply that by a weight of similar size and you're past 2⁵³, where JavaScript numbers stop being exact integers. The biggest amounts are exactly where a silent rounding error would hurt most.

None of this is exotic. It's integers, CHECK constraints, one trigger and a 40-line function. Put together, they make whole categories of money bugs impossible to write instead of just unlikely.

Question for you: do you enforce append-only tables in the database, or trust the application layer? And has anyone here been bitten by float money in JavaScript?

Sidekiq to Kafka: A Mental-Model Map for Rails Developers

Onkar Deokate — Sun, 27 Sep 2026 13:30:00 +0000

TL;DR: If you've spent years with Sidekiq, Kafka can look like "Sidekiq with extra steps". It isn't. Sidekiq moves jobs (commands to do something). Kafka stores events (facts about what happened) in a log that many readers can each read at their own pace. This is the concept map I wish I'd had when I moved from Sidekiq and SQS at work to building a Kafka system myself, including the Sidekiq features you'll have to rebuild yourself.

Where I'm coming from

My day job is mostly Ruby on Rails: background work runs through Sidekiq, and some integrations use SQS. Those tools are great, and for most Rails apps they're the right choice.

Then I built TxFlow, where a single payment event has to trigger five independent reactions (fraud, wallet, notification, audit, analytics). That's where my Sidekiq mental model started giving me wrong answers. Here's the map I ended up drawing.

The one-table version

Sidekiq	Kafka	What actually changes
Job (`perform_async`)	Event / record	A job says "do X". An event says "X happened".
Queue	Topic + partitions	A queue is emptied as jobs are processed. A topic keeps records until retention expires.
Worker processes	Consumer group	Each group reads every event, independently.
Enqueue the same job N times for N handlers	N consumer groups on one topic	The producer doesn't know who's listening.
Built-in retries (25 over ~20 days)	You build it	Kafka has no per-message retry.
Dead set	Dead-letter topic	Also something you build.
No ordering guarantee	Ordering per partition	Key by `user_id` to keep one user's events in order.
Can't replay a finished job	Reset offsets and re-read	The log is still there.
Unique jobs (Enterprise / gems)	Idempotent consumers	Duplicates are normal, so you design for them.
Scale by adding threads/processes	Scale up to the partition count	3 partitions = at most 3 active consumers per group.

The rest of this post goes through the rows that surprised me.

1. Jobs vs events changes who owns the coupling

In Sidekiq, the code that creates a payment usually knows every follow-up:

# app/services/place_payment.rb
FraudCheckJob.perform_async(payment.id)
DebitWalletJob.perform_async(payment.id)
SendReceiptJob.perform_async(payment.id)
AuditLogJob.perform_async(payment.id)

Adding a fifth reaction means editing this file. With Kafka, the producer publishes one fact:

producer.produce("payments.initiated", key=user_id, value=json.dumps(event))

A new reaction is a new consumer group that subscribes to the topic. The producer never changes. That was the real reason I moved to Kafka for this project. Throughput had nothing to do with it.

2. A consumer group isn't a worker pool, it's a subscriber

This one confused me at first:

Same group, many instances: the instances split the partitions between them (like Sidekiq processes sharing a queue).
Different groups: each group gets a full copy of every event.

So "five things react to a payment" is five consumer groups, not five queues and not five job classes.

3. The retries you get for free in Sidekiq are gone

Sidekiq's error handling is so good it's easy to take for granted: 25 retries with exponential backoff over roughly 20 days, then the job goes to the Dead set (kept up to 10,000 jobs or 6 months), plus a sidekiq_retries_exhausted hook.

Kafka gives you none of that. If a consumer keeps failing on one record, it blocks that partition, because offsets are committed in order. In TxFlow I had to build:

in-process retries with exponential backoff (3 attempts),
a payments.dlq topic for records that still fail,
a DLQ handler service that stores failures in Postgres and shows them on a dashboard with a replay button.

It's not hard, but it's real work. Plan for it when you estimate a Kafka migration.

4. Delivery guarantees: different defaults than you'd think

A detail many Rails developers don't know: open-source Sidekiq fetches jobs with BRPOP, which removes the job from Redis when it's fetched. If the process is killed hard (kill -9, OOM) mid-job, that job is lost. On a normal shutdown, Sidekiq pushes unfinished jobs back. Sidekiq Pro's super_fetch closes that gap by keeping in-flight jobs in Redis until they finish.

With Kafka and manual offset commits, a crash mid-processing means the record is delivered again. You get at-least-once delivery by default, and the price is that duplicates are normal. Every consumer with side effects needs to be idempotent (I use a Redis dedup key plus a database primary key for the wallet debit).

5. Ordering is per partition, and you choose the key

Sidekiq makes no ordering promises between jobs. Kafka guarantees order within a partition, and the record's key decides the partition. TxFlow keys payment events by user_id, so all of one user's events land on one partition, in order. That's what you want for applying balance changes.

The flip side is that your parallelism is capped by partition count. You can't add a fourth active consumer to a group reading a 3-partition topic and expect it to do anything.

6. Replay is the superpower

A finished Sidekiq job is gone. A Kafka event stays in the log until retention expires. So you can:

start a new consumer group months later and have it read history (as far back as retention allows),
fix a bug in a consumer and reprocess a time range,
rebuild a projection like analytics counters from scratch.

The test that made it click for me: stop one consumer, fire 10 payments, restart it, and watch it catch up while the other four groups never noticed.

When I'd stay on Sidekiq

Most of the time:

the work is a command with one handler (send this email, resize this image),
you want rich retries and a UI without building them,
you don't need replay or multiple independent subscribers,
your team doesn't want to run a broker.

Kafka earns its operational cost when you have one fact and many independent reactions, need replay, or need ordering per entity at scale. If that's not you, Sidekiq and Postgres will take you a very long way.

Question for Rails folks: what's the one Sidekiq feature you'd miss most if you moved to Kafka? My guess is the retry UI.

DEV Community: Onkar Deokate

The car wash that comes to the car

Four things you can do as a car washer (the video is thirty seconds)

And that's the cast

Three washers. One job. Zero locks.

The WHERE clause is the lock

No photo, no wash. The database agrees.

Proven over real HTTP

What I'd tell myself before starting

Hand over the keys. Get the car back.

Four things you can do as a valet (the video is thirty seconds)

The rule nobody notices

The signal dropped. Mid-trip. With your car.

Why the obvious version loses data

Saved first, sent second

Offline waits. Refused is dropped.

Ten tests

What I'd tell myself before starting

Stop circling the block

Five things you can do as a driver (the whole video is thirty seconds)

The part nobody sees

The map was blank. Every test was green.

Bug one: the worker that was a web page

Bug two: the box with no height

Bug three: every spot in one corner

What I'd tell myself before starting

Your empty parking spot just got a job

Five things you can do (the whole video is under thirty seconds)

What I'm not telling you yet

One booking. Three answers. Only one was true.

Three careful people, three wrong answers

Every figure is one query

The detail that's easy to miss

Surge never touches the owner's line

Don't trust me. Trust the test.

The lesson I paid for

72 commits, 42 decisions, 6 hidden bugs: building a React Native partner app with Claude as a team, not a tool

The setup: /flow, gates, and a paper trail

What went well

1. Choosing a direction from pictures, not paragraphs

2. Review as a stack found bugs that were already in main

3. A ledger of every decision taken on my behalf

4. It opened the app, and that found what tests can't

What went badly

1. The AI's own plan had bugs, and reviews caught them late

2. Fixes introduced regressions

3. Wall-clock time, mostly rate limits

4. The environment lied, and it nearly cost a false bug hunt

How Opus 5.5 helped

How AI actually helps (and where it doesn't)

The token-optimisation playbook

The takeaway

Poison Messages in Kafka: Retries, a Dead-Letter Queue, and the Replay Shortcut I'd Fix

The problem: poison messages

Step 1: separate "try again" from "never going to work"

Step 2: a useful DLQ envelope

Step 3: order of operations

Step 4: make failures visible

Not everything needs a DLQ

The replay shortcut I'd fix

Checklist

Money in a Parking App: Paise, Basis Points and a Ledger Postgres Won't Let You Edit

Rule 1: no floats, ever

How a price is built

Checked twice: in code and in the database

Rates have history

The ledger: double-entry, append-only

"Append-only" enforced by the database

Splitting refunds without losing a paisa

Sidekiq to Kafka: A Mental-Model Map for Rails Developers

Where I'm coming from

The one-table version

1. Jobs vs events changes who owns the coupling

2. A consumer group isn't a worker pool, it's a subscriber

3. The retries you get for free in Sidekiq are gone

4. Delivery guarantees: different defaults than you'd think

5. Ordering is per partition, and you choose the key

6. Replay is the superpower

When I'd stay on Sidekiq

The setup: `/flow`, gates, and a paper trail

2. Review as a stack found bugs that were already in `main`