Over a million chess reviews a month, and the engine runs on your phone, not my server

Mehdi Ben Haddou — Sat, 26 Sep 2026 14:01:39 +0000

Most chess sites limit free game review for a boring reason: running a chess engine over every move of every game costs real CPU, and someone has to pay for it. If a review takes 20 seconds of server compute and you have 40,000 of them a day, you have a bill.

We started Chessigma in March 2025 because players kept complaining about that limit. The trick that makes it free and unlimited is not clever. The engine is compiled to WebAssembly and runs in your browser tab, on your own device. Our server fetches the game, works out a few stats at the end and stores the result. Today that's over a million reviews a month, and the expensive part of each one runs on somebody else's CPU.

That part worked on day one. What I didn't expect is how much of the next year would go into one question: how do you tell a slow run from a dead one, on a device you can't see?

The split

Roughly, this is who does what:

 your phone / laptop                         my servers
 ------------------------------------        ---------------------------
 download engine (.wasm, 7.28 MB)   <------  CDN
 spin up 1-2 Web Workers
 evaluate every position   (progress 0 to 80%)
 grade each move           (Sigma down to Clown)
 post the finished result           ------>  store it, compute a few
                                              stats, send them back

Mobile gets one worker. Desktops with more than four cores get two. Nothing fancy, and it has held up. (Sigma and Clown are our move labels. A friendly trademark chat with Chess.com meant we couldn't borrow theirs, so a blunder here is a Clown. Nobody has complained.)

The cost side is exactly what you'd hope. The failure side is where it gets interesting, because when the work runs on someone else's device, every failure happens somewhere you have no logs.

Failures that never throw

On a server, a job that dies usually tells you. In a browser tab on a cheap Android phone, a lot of things just... stop:

The .wasm starts downloading, the connection drops halfway, and the worker never says a word.
The OS freezes the WebView when the user switches apps. Your timers stop. When they come back, it looks like nothing happened for two minutes.
The runtime traps inside the engine on some devices, and the worker goes quiet.
The engine is fine, but it's slow, because it's a four-year-old phone on a train.

So we had a watchdog. It polled every two seconds, and if the analysis looked stuck, it gave up on the run. Reasonable. Here is the line that decided "stuck":

const STALE_MS = 20_000;
const CAP_MS = 60_000;

// keep waiting only if BOTH are true
if (msSinceProgress < STALE_MS && msElapsed < CAP_MS) return;
// ...otherwise give up

Read it slowly. It keeps waiting only if progress moved recently and the whole run is under 60 seconds. So any review that took longer than a minute got killed, even if it was moving along happily. A long game on a slow phone takes longer than a minute. That's not a stall, that's just a phone.

It got worse. Giving up flipped the "analyzing" flag off without ever setting "ready", so the UI moved on to the report screen and rendered its initial state. Every accuracy was zero, every move count was zero. It looked like the engine had produced garbage. It hadn't produced anything.

A user wrote in: "analysis stops, no move classifications". When I went to the data:

The watchdog fired about 3,100 times in 14 days.
At the moment it fired, the median run was 48.66% done. These were healthy runs, cut in half.
In the mobile app, where the watchdog was switched on, 39.8% of users hit at least one failed analysis in those two weeks. Almost all of them on Android.

My first theory was wrong. I was sure we were saving corrupted engine output and serving it back from a cache. We weren't: the game in the report had zero analysis rows. The bug was one &&.

The fix: make "stuck" a pure function

The rewrite had one rule. Elapsed time only means something before progress has ever moved. Once the engine has reported anything, the only clock that matters is "time since the last progress".

I pulled the decision out of the React hook into a pure function with no timers, no React and no imports, so it can be tested in plain Node:

export function analysisWatchdogVerdict(input: WatchdogInput): WatchdogVerdict {
  // A frozen timer (backgrounded WebView) makes every clock lie,
  // so discount the late part of this tick before reading any budget.
  const skewMs = input.msSinceLastTick > input.tickMs * 3
    ? input.msSinceLastTick - input.tickMs
    : 0;
  const startClock = input.msSinceStart - skewMs;
  const progressClock = input.msSinceProgress - skewMs;

  // Boot leg: progress never moved, so elapsed time is all we have.
  if (input.lastProgress <= 0) {
    return startClock >= BOOT_BUDGET_MS
      ? { kind: 'never_started' }
      : { kind: 'running' };
  }

  // Mid-run: only the progress clock counts. No absolute cap.
  const budgetMs = input.lastProgress >= 80
    ? METRICS_STALL_BUDGET_MS  // network phase
    : ENGINE_STALL_BUDGET_MS;  // CPU phase, one position at a time
  return progressClock >= budgetMs
    ? { kind: 'stalled' }
    : { kind: 'running' };
}

(Trimmed. The real one also handles "engine never said it was ready" and returns how far over budget it was, for telemetry.)

The part I'm happiest with is that every budget now has its arithmetic written next to it instead of being a round number someone liked:

Boot, 90 s. 7.28 MB is 58 Mbit. At a sustained 1 Mbps that's 58 seconds of download, plus a few seconds to compile the wasm on a mid-range Android, plus the handshake and the first position. About 65 seconds at the slow end. 90 gives headroom, and below roughly 0.7 Mbps the download genuinely can't finish, so saying so is the right answer.
Engine stall, 20 s. Progress fires once per position, and the engine's own per-position timeout tops out around 14 seconds at the depth we use. A CI check pins that relationship, so if someone raises the depth later, the build fails instead of the watchdog quietly killing slow runs again.
Network stall, 45 s. After the engine phase, the gaps are HTTP calls with retries. Three attempts that each hit a 14 s function timeout, plus backoff, is 43 seconds.

And because it's a pure function, I could do the one test that matters: put the old 60-second cap back in and watch CI go red.

The other half: the bytes have to arrive first

All of this assumes the engine file actually reaches the device. Around the same time we learned how optimistic that was, from a completely different direction.

In April we moved every static asset (JS, CSS, the engine) to a CDN on a separate domain. Standard assetPrefix stuff. Four months later, someone on our Discord posted a screenshot of the site with no styles at all, on an iPad. Then another one.

We checked everything we could think of. DNS resolved fine on six public resolvers. The TLS chain was fine. Every file returned 200. Nothing in our error tracking. And that last one is the actual lesson: our analytics script was part of the bundle served from the CDN. A user who couldn't reach the CDN never sent us a single event. For four months, the only monitoring we had for this failure was people bothering to complain.

We added a tiny beacon served from the main domain, and the first day of data said roughly 150 page loads a day were arriving with no CSS. iOS Safari was heavily over-represented. The causes were boring and plural: content blockers and filtering DNS treating a different domain as third party, corporate proxies with allowlists, and TLS interception, which fails hard on a .dev domain because the whole TLD is HSTS-preloaded and there's no "continue anyway" button.

Two findings from that week I'd put on a poster:

2 CSS files break the page, 37 JS files don't. Block all the JS and the site looks perfect, just dead. Block two stylesheets and it looks like 1998. So the stylesheets are where a fallback pays for itself.

You can't catch the first stylesheets with an error listener. Our first fix did exactly that and rescued none of the CSS. React hoists stylesheets to the top of <head>, and a render-blocking stylesheet blocks every script after it, so by the time the parser reaches your listener, the CSS has already failed. We measured it on Chromium, Firefox and WebKit. Same order every time.

Checking document.styleSheets doesn't help either. A failed sheet is still listed there, and you can't read a cross-origin sheet's rules, so an empty 200 from a blocker looks healthy. What finally worked is almost embarrassing:

/* last line of our global stylesheet */
html { --cs-stylesheet: ok; }

// inline, in the HTML, so it doesn't depend on the CDN
const v = getComputedStyle(document.documentElement)
  .getPropertyValue('--cs-stylesheet');

if (!v.trim()) {
  // our CSS never reached the CSSOM, whatever the reason:
  // refused, DNS, TLS, 403, 404, blocked, empty body.
  // Re-request every CDN stylesheet from the main origin.
}

One custom property covers every failure shape at once, because it doesn't ask why the CSS is missing. It asks whether the CSS is there.

Two smaller things that bit us along the way, in case they save you an afternoon:

Our CDN (Cloudflare) cached 404s at the edge for 4 hours. So "just hard refresh" did nothing for anyone who hit a missing file once. A browser refresh can't clear an edge cache.
Cloudflare decides what to cache by file extension, not MIME type. .js is on the default list. .wasm isn't. Our 20 KB engine loader was served from the edge, and the 7.28 MB engine right next to it went back to origin every time, with identical cache headers. curl -I won't show you this properly either, because it sends HEAD. Test with a GET.

What I'd tell myself a year ago

Running the engine on the user's device was the right call, and I'd do it again. It's why the review can be free and unlimited at all. But it moves your reliability problem somewhere you can't see, and a few habits make the difference:

Your monitoring can't live in the thing it monitors. If the analytics ships inside the bundle, a failed bundle is silent. Keep one tiny beacon on the main origin.
"Slow" and "dead" need different clocks. Elapsed time says nothing once work is progressing. Time since last progress does.
Write the arithmetic next to the timeout. "60 s" came from nowhere and killed half-finished runs. "7.28 MB at 1 Mbps" can be argued with.
Pull decisions out of hooks. The watchdog bug lived unnoticed inside a useEffect. As a pure function, the test that would have caught it is a few lines of plain Node.

If you want to see the result, paste any Chess.com or Lichess username on chessigma.com and watch your laptop fans do my job.