DEV Community: 田WB

How I take a paper game online, one decision at a time

田WB — Thu, 08 Oct 2026 11:56:31 +0000

My son is 9. He is reading Ben Orlin's Math Games with Bad Drawings, and he picks the next game. I build that one with a model in the editor.

The model is fast at a first version. It is careless about where the truth lives, and it will write that truth down twice. So the work I keep is short. I write the decision in a file, I choose which machine owns the rules, and I play the position the first check gets wrong.

By 1 October, four games were playable in the browser. The notes are dated, so the sequence below is the one that happened.

He picks, and the decision goes in a file

A game in that book fits on a table. Online it has to answer questions the book skips. Who checks a move? What happens when the other connection drops? Can two browsers disagree about a freehand curve?

I write the answer before the code spreads. The file says what is true, which machine owns it, and which shortcut is already dead. The next session starts from that file, whether the session is mine or the model's.

The Sprouts notes are dated 23 August 2026. The online-play notes are dated 26 August. The maze notes are dated 16 September. Ultimate tic-tac-toe is 27 September. The room layer is 1 October.

The first game keeps two models

Sprouts came first. You join two dots with a curve, and a new dot grows on the curve. A dot can meet three curves.

The screen stores the sample points, so the line looks like a pen. The rules store dots, links, and a degree. One move updates both. The first version was two people on one screen. A second city, and a computer opponent, waited until those two models had a place to live.

The first endgame check added up the lives left on the board. A total under 2 means the game is over, and that half is right. Real games kept hitting a position that sum misses. Two new dots, each sealed in its own loop, still add up to 2 lives, and neither dot can reach the other. From 23 August until 27 September, a player in that position pressed a button to say they had no move. Then the check started walking the faces after every move. That position showed up with a person at the screen, before a computer opponent had to trust the same check.

The server runs the session

For online play I wanted one process to hand out a room code, track the seats, remember whose turn it is, and notice a disconnect. The Sprouts geometry stayed in the TypeScript that already drew the line. A second copy of that engine in Go would drift away from the freehand curves.

The Go server runs the session. The browser that draws the curve checks crossings, dots in the way, and a degree of 3. The move goes out as that list of points. The other browser draws the points and updates its graph. A second geometry check on a freehand curve can disagree with the first, so only the browser that drew the line runs it.

The points live in board space. A different window size does not move the dots. While the line is still being drawn, the other screen sees the stroke.

The next game keeps a different home for the rules

Franco maze came next. Each of you builds a maze for the other, then walks it blind. You do not know the walls. A browser that answers "you hit a wall" can lie, and a dropped connection stalls the turn.

The server holds both mazes and answers the wall check. The browser sends the step and draws the result. The Sprouts split would be the wrong split here, because the hidden board is the game.

Ultimate tic-tac-toe has no hidden board and no curve. Nine small boards, and the cell you pick sends your opponent to one of them. The rules are a short pure function. That function lives once, in TypeScript, and the shared-screen game uses the same file. Online, the server forwards the move. The other browser runs the function. A failed check is treated as a broken connection.

A second copy of those rules in Go would have to change every time a small-board rule changed. I left them in the one TypeScript file.

Penny Wise is the coin game, added on 1 October, for 2 to 6 players. The server is the referee. A turn lasts 30 seconds. Someone can leave and the hand continues.

Sprouts geometry stays on the browser that drew the line. Franco maze and Penny Wise stay on the server. Ultimate tic-tac-toe stays in one TypeScript file, because both sides can run it and get the same answer. That placement is the note. The model fills in the code around it.

After three games, one room

Through September the pages and the Go server lived in one repo. On 30 September I split them. nginx serves the pages. The HTTP API is tRPC. The game socket has its own port. Each game is its own package.

On 1 October the old matchmaking became a room, and every game uses it. You create a room, send the code, sit, mark ready, and start. You can switch games in the same room. A new game is a package plus one line in the list the room builds at startup.

for _, l := range []games.Logic{
    sprouts.New(),
    labyrinth.New(),
    ultimate.New(),
    pennywise.New(),
} {
    h.games[l.ID()] = l
}

labyrinth is Franco maze. The room talks to a game only through one interface. The interface says how many players the game wants, how a game starts, and what happens when someone leaves. A two-player game decides that the other person has won, inside that same method.

The socket code is split the same way. One package accepts the connection. One package is the room. One package is the game in progress, with the seats and the timer. One package is a single connection, its queues and its heartbeat. A package starts as an interface. A helper with no interface goes back into the package that calls it.

A logged-in player who drops keeps the seat and can come back. Playing needs no account. A finished game is saved, and stepping through the moves needs a login. Accounts sit in MySQL. The session is a cookie.

A few of those choices are also rules in the repo, so the next session inherits them. The user row is the user type, passed through as it is. A setting with one production value is a constant in that package. The room tests construct the real games.

The page after the game

On 2 October the explanation stopped being a stack of paragraphs. Sprouts and Franco maze each have one page you can poke. The layout, the figures, and the little demos exist once. Each language is a text file with a fixed shape. Leave out a field and the TypeScript build fails. On 5 October each of those pages got its own URL.

A computer opponent, then a second site

Quick join is how a computer opponent shows up. If you are the only person in that automatic room, and the switch on that screen is on, the site waits 10 seconds. Nobody else arrives, and the empty seat becomes a computer that tries to win. There is one strength. A second person arriving during those 10 seconds cancels it, and you play each other.

The computer for Sprouts, ultimate tic-tac-toe, and Penny Wise runs in the page. The Franco maze computer runs on the server, because the server is still the one holding the walls, so that game needs a connection.

The English site is a separate deploy, with Cloudflare in front. Players, logins, and saved games stay on that site. Google login is there, and the username is the email from the first sign-in. On 6 October I added a page for a parent, about sitting down for one game and then reading the math in it.

The Chinese side is a WeChat mini game. It has Sprouts, and its own login.

What I still check by hand

I still play the awkward position. For Sprouts it was two dots that cannot reach each other. For Franco maze it was a player who can lie about a wall. For ultimate tic-tac-toe it was a rule I would otherwise keep in two languages.

I built this with my 9-year-old son. He picks the game. The pages are TypeScript and canvas, with no framework. The server is Go. HTTP is tRPC, and the game is a WebSocket. Accounts are in MySQL.

Math Charm

If you play one, tell me which game a kid picks and which rule was hard to see. We hope kids play for a while and start to like math along the way.

How I Built an AI Birthday Photo Generator with Cloudflare Workers, Gemini 2.5 Flash, and FLUX.2 Pro

田WB — Sat, 11 Apr 2026 04:32:46 +0000

TL;DR: Upload a selfie → Gemini analyzes the photo and writes 3 birthday scene prompts → FLUX.2 Pro generates the images → Cloudflare R2 stores them. The whole backend runs on Cloudflare Workers with zero servers.

I recently launched bdayphoto.com, an AI-powered birthday photo generator. Upload your photo and get 3 unique AI birthday celebration scenes in about 60 seconds. Here's how I built the whole thing on Cloudflare's serverless stack.

Before → After — one selfie, three AI-generated birthday scenes:

Original photo	Scene 1	Scene 2	Scene 3

The Stack

Frontend: Next.js 15 (App Router) → static export → Cloudflare Pages
Backend:  Cloudflare Workers (TypeScript)
Database: Cloudflare D1 (SQLite)
Storage:  Cloudflare R2
Cache:    Cloudflare KV (sessions)
Queue:    Cloudflare Queues
AI:       Gemini 2.5 Flash (via Replicate) + BFL FLUX.2 Pro
Payment:  PayPal
Auth:     Google OAuth

The entire backend runs on a single Cloudflare Worker. No EC2, no containers, no ops headaches.

The Core Pipeline

The generation flow looks like this:

User uploads photo
      ↓
Worker validates + deducts credits + enqueues job
      ↓
Queue consumer picks it up (runs up to 15 min)
      ↓
Step 1: Gemini 2.5 Flash analyzes the photo → outputs 3 scene prompts (JSON)
      ↓
Step 2: Submit 3 FLUX.2 Pro jobs sequentially → each fires a webhook when done
      ↓
Webhook handler saves images to R2, finalizes task
      ↓
User polls /api/task/:id → gets results

Step 1: Gemini Analyzes the Photo

The hardest part wasn't the image generation. It was writing a prompt good enough to make Gemini output exactly what FLUX needs.

I use Gemini 2.5 Flash via Replicate's API. The system prompt is ~800 words and instructs Gemini to:

Count people in the foreground (ignore background bystanders)
Describe each person's face features in detail (for face preservation in the generated image)
Design 3 completely different birthday scene themes
Output a structured JSON with start_prompt, end_prompt, and 3 scenes

The JSON structure separates shared prompt parts from scene-specific content:

{
  "people_count": 1,
  "start_prompt": "This is the same person from the reference photo. Preserve their exact face shape...",
  "end_prompt": "Shot on Canon EOS R5, 85mm f/1.4, photorealistic, 8K ultra HD",
  "scenes": [
    { "name": "Golden_Gala", "prompt": "Glamorous gold ballroom with 40 metallic gold balloons..." },
    { "name": "Tropical_Paradise", "prompt": "Vibrant beach party setting with palm trees..." },
    { "name": "Enchanted_Garden", "prompt": "Magical outdoor garden with floral arches..." }
  ]
}

When submitting to FLUX, I assemble the full prompt as:

const fullPrompt = [analysis.start_prompt, scene.prompt, analysis.end_prompt]
  .filter(Boolean)
  .join(' ');

This makes it easy to tune the shared "face preservation" instructions without touching each scene prompt.

Step 2: FLUX.2 Pro Image Generation

I use BFL's FLUX.2 Pro directly (not via Replicate or fal.ai). The BFL API supports:

input_image + input_image_2: both set to the user's photo — this enables face-consistent generation
webhook_url + webhook_secret: BFL calls back when done instead of polling

const body = {
  prompt: fullPrompt,
  input_image: dataUri,
  input_image_2: dataUri,   // face reference
  width: 1080,
  height: 1920,
  output_format: 'jpeg',
  safety_tolerance: 5,
  webhook_url: webhookUrl,
  webhook_secret: webhookSecret,
};

I submit 3 scenes sequentially, not in parallel. BFL's API occasionally returns "Task not found" errors when you hammer it too fast — sequential submission with a small gap is much more reliable.

Handling Webhooks on Cloudflare Workers

BFL fires a webhook when each image is ready. The webhook handler:

Verifies the webhook_secret (a UUID generated per task)
Downloads the image from BFL's CDN
Uploads it to R2
Updates the bfl_tasks record
Checks if all 3 are done → finalizes the parent task

// Idempotent finalization using CAS update
const updateResult = await env.DB.prepare(
  `UPDATE tasks SET status = 'done', r2_key_1 = ?, r2_key_2 = ?, r2_key_3 = ?, updated_at = ?
   WHERE id = ? AND status != 'done'`
).bind(r2Keys[1], r2Keys[2], r2Keys[3], now, taskId).run();

if (!updateResult.meta.changes || updateResult.meta.changes === 0) {
  // Already finalized by another concurrent webhook, skip
  return;
}

The AND status != 'done' guard makes the finalization idempotent — safe even if two webhooks arrive simultaneously.

Webhook Loss Compensation

Webhooks can fail or get lost. I added a polling compensation mechanism triggered when the user polls /api/task/:id:

// If task is generating and it's been > 30 seconds since submission,
// actively poll BFL's result API for any bfl_tasks that haven't completed
if (task.status === 'generating') {
  ctx.waitUntil(compensateMissingResults(taskId, userId, env));
}

The compensation function queries bfl_tasks where status = 'generating' and the task was submitted more than 30 seconds ago, then polls BFL directly. ctx.waitUntil() runs it asynchronously without delaying the HTTP response.

D1 Schema Design

The database has three main tables:

-- Tracks the overall generation job
CREATE TABLE tasks (
  id TEXT PRIMARY KEY,
  user_id TEXT NOT NULL,
  status TEXT NOT NULL,         -- pending → analyzing → generating → done
  gemini_analysis TEXT,         -- raw JSON from Gemini
  analyze_duration_sec REAL,
  scene_name_1 TEXT, scene_name_2 TEXT, scene_name_3 TEXT,
  r2_key_1 TEXT, r2_key_2 TEXT, r2_key_3 TEXT,
  credits_cost INTEGER,
  error_message TEXT,
  expires_at TEXT,
  created_at TEXT, updated_at TEXT
);

-- One record per FLUX job (3 per task)
CREATE TABLE bfl_tasks (
  id TEXT PRIMARY KEY,
  task_id TEXT NOT NULL,
  scene_index INTEGER NOT NULL,  -- 1, 2, or 3
  bfl_id TEXT,                   -- BFL's job ID
  polling_url TEXT,
  webhook_secret TEXT,
  status TEXT NOT NULL,          -- pending → generating → saving → done | failed
  r2_key TEXT,
  error_message TEXT,
  created_at TEXT, updated_at TEXT
);

-- Tracks concurrent generation lock per user
-- users table has a `generating_since` TEXT field
-- Atomic lock: UPDATE users SET generating_since = ? WHERE id = ? AND (generating_since = '' OR generating_since < ?)

The atomic lock for preventing concurrent generations is clever: it's a single UPDATE with a conditional WHERE — if the update affects 0 rows, someone else is already generating.

Credits System

I track credits with an event log pattern:

// Deduct credits + create task + log — all in one D1 batch
const batch = [
  env.DB.prepare(
    'UPDATE users SET credits = credits - ? WHERE id = ? AND credits >= ?'
  ).bind(creditsCost, userId, creditsCost),
  env.DB.prepare(
    'INSERT INTO tasks ...'
  ).bind(taskId, ...),
  env.DB.prepare(
    'INSERT INTO credit_logs (change_amount, balance_after, reason) VALUES (?, ?, ?)'
  ).bind(-creditsCost, newBalance, 'generate'),
];
await env.DB.batch(batch);

If the first statement affects 0 rows (concurrent deduction), I clean up and return a 403. The batch is atomic at the D1 level.

Partial failures are handled gracefully: if 1 of 3 FLUX jobs fails, I refund ceil(credits_cost * failed_count / 3) credits.

Frontend: Next.js + Static Export

The frontend is Next.js 15 with output: 'static' deployed to Cloudflare Pages. Static export means there's no Node.js server — just HTML/CSS/JS on the CDN.

For SEO, I needed server components to export metadata. Since the app was originally all 'use client', I refactored each page:

src/app/page.tsx          ← server component, exports metadata
src/components/home-page.tsx  ← client component with all the interactivity

This way Next.js can statically render the <head> with proper <title>, <meta>, and JSON-LD tags while keeping the interactive bits client-side.

Lessons Learned

1. Queue consumers are the secret weapon of Cloudflare Workers.
Without Queues, you'd have to orchestrate long jobs externally. With Queues, you get 15 minutes of wall time for complex AI pipelines.

2. Webhook + polling compensation is more robust than polling alone.
Webhooks are fast but can be lost. Pure polling is slow. The combination — webhooks for speed, compensation polling as a fallback — gives you reliability without burning money on unnecessary API calls.

3. Idempotent operations everywhere.
Multiple webhooks can fire. Queues can retry messages. D1 batches can partially fail. Design every write as a CAS (Compare-And-Swap) update with conditional WHERE clauses. OR IGNORE and AND status != 'done' guards have saved me from data corruption multiple times.

4. BFL over Replicate for FLUX.2 Pro.
BFL is the official API from Black Forest Labs (the FLUX team). It's cheaper, faster, and the parameters are documented correctly. Third-party platforms like Replicate have slightly different parameter semantics.

5. Split Gemini's output into start_prompt + scenes + end_prompt.
This separation makes it easy to iterate on face-preservation instructions globally without regenerating every scene prompt. It also keeps individual scene prompts concise and focused.

What's Next

Pinterest strategy for organic reach
More scene themes (holiday, vintage, anime style)
Batch generation improvements

Check out the live product at bdayphoto.com — you get 10 free credits on signup (no credit card required).

Happy to answer any questions about the architecture in the comments!