The Occasional Jam No. 06

No. 06 devlog

Jam Cat How?

6 min read

How does this site work? Peek behind the curtain.

I build and run JamCatWow by myself, and I originally made it so my family and I could play word games at each other. Both facts shaped what follows: the machinery is simple on purpose, and sharing is the point. The nerdy asides are skippable.

Days of puzzles queued ahead
90
Give or take. A job at 4am tops the queue back up.
Days of the archive that stay free
14
Older days are for Supporters.
File per game, per date
1
In a private bucket, never rows in a database.

The whole machine

Five parts. My Mac makes the puzzles. A private bucket holds them. The site hands them out, one day at a time. A small database remembers accounts. You, hopefully, play.

Flowchart: you, in a browser, play and share on jamcatwow.com at the edge. The site makes gated reads from a private bucket holding a file per game per day, and syncs results to Supabase, which holds accounts. My Mac makes the puzzles and publishes them into the bucket. Flowchart: you, in a browser, play and share on jamcatwow.com at the edge. The site makes gated reads from a private bucket holding a file per game per day, and syncs results to Supabase, which holds accounts. My Mac makes the puzzles and publishes them into the bucket.
The whole machine. Arrows are the only ways data moves.

For the builders: static pages on a CDN, a handful of edge functions, one storage bucket, and a managed Postgres. There is no server to babysit.

Where the puzzles come from

Every puzzle is made ahead of time by Python scripts on my own computer. Each game has its own generator, and they work in very different ways, but each one has to show that a day deserves to ship before it ships. The questions are the same for every game:

  • Can the day be won at all?
  • Is it fair, neither starved for answers nor drowning in them?
  • Would it embarrass me?

The scripts that build tomorrow's puzzle know tomorrow's answers, which is why I can't open-source any of this.

Every puzzle passes through one door on its way up: the Publisher. It stamps the date and the game number, then checks the puzzle against The exact list of rules a day's file must satisfy.. It is the only code that can write to the bucket, so nothing unchecked gets there. The site keeps its own copy of the schema, in TypeScript, and checks every puzzle again after downloading it. A bad puzzle gets caught twice: once on my Mac, and again before the game sees it.

For the builders: how two hand-written copies of one schema stay honest

Hand-mirrored rules drift, and I know better than to trust myself to keep them in sync. So a shared set of example days runs through both copies on every push, and if they disagree, my laptop blocks the push seconds after I typed it. Where the code comes from lets you break it yourself.

Every morning at 4am, while I'm asleep, my Mac tops the queue back up to about ninety days. The job keeps no state of its own. It lists what is in the bucket, compares that with ninety days from today, and makes only the missing tail. Miss a run, miss a week, and the next run fills the gap. So the site keeps serving new games even when life gets busy. Which it does.

When a game's queue runs low, the job raises an alarm, and the robot checks for it at the start of my working sessions. The job used to post a notification on my Mac instead. That notification never once appeared, and one game ran out of puzzles in August before anyone noticed.

How a Daily reaches you

Finished puzzles live in a private bucket that your browser cannot reach, and neither can anyone else's. Every request goes through a small gate that knows the date and the rules: the newest two weeks are free, anything older is for Supporters, and future days do not exist.

Sequence diagram: your browser asks the Daily gate for a day's puzzle. The gate checks the day is inside the free window, does a signed read from the private bucket, and returns the Daily. The browser checks it, then plays. A note says tomorrow's Daily exists already, and asking for it gets a 404. Sequence diagram: your browser asks the Daily gate for a day's puzzle. The gate checks the day is inside the free window, does a signed read from the private bucket, and returns the Daily. The browser checks it, then plays. A note says tomorrow's Daily exists already, and asking for it gets a 404.
One day at a time. The gate holds the keys and the calendar.

Tomorrow's puzzle is sitting right there, finished, and the gate will still tell you there is nothing to see. No clever URL gets around it, because the gate is the only thing holding the bucket's keys. I'm strict about this one, because a spoiler is the fastest way to kill a daily habit.

For the builders: the two kinds of no

The gate refuses the deep past and the future with different status codes. A locked archive day is a 403, real but off limits. Tomorrow is a plain 404, because even a 403 would confirm something is there. Supporter status is checked only when it could change the answer, so the everyday request is decided without touching the database.

The next puzzle unlocks at midnight in New York, for everyone at once, so the Daily you are bragging about is the one your friends are stuck on. That was the easy part. What day it is turned out to be the hardest question on the site.

If a day's file ever fails the site's check, you get a practice game instead of an error page. My bad day shouldn't become yours.

Beat the Creator

Future days do not exist, with one exception: me. Before a Daily goes live I can play it blind, the way you will, and my score is written into the puzzle's own file. Every Daily ships with a small boss fight: beat my score, and your share says so.

The live site cannot write those scores, or anything else. No deploy has ever been given keys that can change a Daily, so from the internet's side the files are read-only, as an absence rather than a setting someone could flip.

The site itself

The site is a SvelteKit app served from Cloudflare's edge, which means the pages are already sitting in a data center near you before you ask for them. Almost every page is built at deploy time and served as a file. The few dynamic ones, like the gate, run as small functions at the edge, with no servers to keep warm. I picked that for a plain reason: the ops team is me, and I would like to sleep. These days most of the code is written by a robot.

Once the puzzle arrives, the game runs entirely in your browser, timer and scoring included, and the server takes your word for the result. In most systems that would be a hole. Here, the only thing a forged score can steal is a brag, so I drew the line where the stakes are.

Your data, and where it lives

Almost everything stays on your device, which is why you can play without an account. The servers keep the puzzles and, only if you make a free account, your email and a synced copy of your results.

On your deviceOn the servers
Today's game, in progressEvery puzzle, past and future
Your results: tier and points for every day you playedA copy of your results, only if you sign in
Streaks and statsYour email, only if you make an account
The server's copy of your results exists only if you sign in.

The sync rule: for each day, the best score wins. Play on your phone at lunch and your laptop at night, and both end up with the better score. A stale device can never downgrade a good day, and nobody ever sees a merge screen.

For the builders: why one rule replaces a sync engine

Taking the max is commutative, associative, and idempotent, so devices can sync in any order, repeat themselves, or vanish for a month and still agree, with no conflicts and no clocks. The distributed-systems crowd has formal names for this shape. Mine is "best score wins".

The site also counts visits. A random tag in your browser lets me tell a thousand players from one very dedicated one, because without it I can't see whether anyone comes back tomorrow, and that is the question I'm building against. It carries no name and no email, it feeds a dashboard and not an ad network, and if your browser sends Do Not Track, the counting skips you.

Sharing

This is the part the site exists for. When you share a score, your result rides inside the link itself, in the string after the question mark. The server stores nothing about it: no share table, no lookup, no expiry date.

Sequence diagram: you send your share, with the score in the link, to a friend's chat. The chat app unfurls it, and jamcatwow.com answers with a title carrying the score and a card for your tier. Your friend taps through, sees your result and one Play button, and plays the same day. A note says nothing was stored anywhere: the share lives in the link. Sequence diagram: you send your share, with the score in the link, to a friend's chat. The chat app unfurls it, and jamcatwow.com answers with a title carrying the score and a card for your tier. Your friend taps through, sees your result and one Play button, and plays the same day. A note says nothing was stored anywhere: the share lives in the link.
One share, two fetches, zero database rows.
A share from this year will still work in five years, because there is nothing to delete.

The chat app shows a card for your game and your tier, with your number and points in the title under it, and the page your friend lands on is rebuilt from the link every time. The cards used to be drawn on demand at the edge. Why they are files now is a post of its own.

The link carries your performance and never the answers, so the friend you're taunting gets a fair shot. And yes, since the score lives in an editable link, you could hand-craft one claiming 999 points. The link will print your lie, and the answers stay safe either way.