Play · architecture profile

Bubbles

Deterministic bubble puzzles with a shared radio. A browser game served as static assets, with a separate cloud Worker for optional profiles, high scores and sign-in.

LiveArchitecture reviewed 7 November 2026Dossier reviewed 19 October 2026

How it is built.

Bubbles runs the game in the browser. One Worker serves the built assets; a second Worker at api.bubbles.loftwah.com provides optional profile sync, high scores and email magic-link sign-in. A React shell owns menus, settings and accessible controls; Phaser renders play; an Effect-based domain layer keeps the simulation deterministic. Music is delegated to LoftwahFM's pinned radio client while the game keeps its own audio graph.

Stack
Phaser 3.87, React 19.3, TypeScript, Vite 5, Effect 4Evidence: package.json
Runtime
Two Cloudflare Workers: `bubbles` serves the Vite build through ASSETS; `bubbles-cloud` serves api.bubbles.loftwah.comEvidence: wrangler.jsonc; wrangler.cloud.jsonc
Storage
D1 `bubbles-cloud` for optional profiles and high scores; localStorage for the active save, settings and score historyEvidence: wrangler.cloud.jsonc; src/persistence/profile.ts; src/persistence/high-scores.ts
Identity
Optional email magic-link sign-in with an opaque HttpOnly `bubbles_session` cookie; the game is playable without an account.Evidence: src/cloud/lib/cookies.ts; src/cloud/lib/resend.ts
Delivery
Cloudflare custom domain bubbles.loftwah.com for the game; scripts deploy the game and cloud Workers separatelyEvidence: wrangler.jsonc routes; package.json scripts
Integrations
LoftwahFM radio client 1.2.0; Resend for magic links; a public portfolio-analytics route on the cloud Worker consumed by WoodhouseEvidence: package.json; src/app/music-transport.ts; src/cloud/routes/portfolio-analytics.ts; Woodhouse src/data/portfolio-analytics.ts

The shape of the system.

  1. Game clientPhaser owns play and rendering; React owns menus, settings and the controls a keyboard can reach.Evidence: src/app; src/presentation
  2. DomainEffect services keep game state and rules separate from presentation.Evidence: package.json (effect); src/app
  3. Optional cloudA second Worker owns profile sync, high scores and magic-link sessions. It is not on the path to opening or playing the game.Evidence: src/cloud; wrangler.cloud.jsonc
  4. AudioThe game keeps its own effects and volume. LoftwahFM's client selects stations and queue state; it does not replace the host audio graph.Evidence: src/app/music-transport.ts; FM docs/radio-game-integration.md

A local-first game with an account that is optional.

Most of this portfolio's games look similar from the outside and are built differently inside. Bubbles is the clearest case of a game that keeps the server off the critical path: one Worker serves files, and everything that makes the game a game happens in the browser.

The optional account is the interesting part. A second Worker owns magic-link sign-in, profile rows and high scores. Because the local save exists first, sign-in adds sync rather than unlocking play. That removes an entire class of failure from the first session — no session, no account, no database write before the game starts — and moves the hard problem to conflict handling between devices, which is the problem the product actually has.

The audio split is the part worth copying. LoftwahFM's client manages which station is playing and what comes next. Bubbles keeps the Web Audio graph, effects and mute policy. Neither side needs to know the other's internals, which is why the same client also works in Fighter, SHOALSHOT and Protocol 11.

Engineering decisions worth knowing.

  • Local first, with an optional account

    The save exists before sign-in, so a backend outage cannot take it away. The trade-off is that browser storage limits and migrations belong to the game; the cloud profile is a convenience, not the source of truth for play.

  • Two Workers, because they have different jobs

    The game Worker serves files and nothing else. The cloud Worker owns identity and sync, which keeps cookies and database writes out of the static asset path.

  • Music is a capability, not a second platform

    Pinning one versioned radio client keeps station logic out of the game. The client may change station and queue state; the game still decides how loud anything is.

What it connects to.

  • BubblesLoftwahFMradio client 1.2.0two-way

    Bubbles pins @loftwahfm/radio-client 1.2.0 for station and queue state, and its host audio manager keeps effects, volume and mute. The same client sends anonymous listening-v1 events back to LoftwahFM, which makes this pair two-way without a shared account.

    Evidence: Bubbles package.json dependency URL; src/app/music-transport.ts; LoftwahFM packages/radio-client/src/telemetry.ts

  • WoodhouseBubblesportfolio analytics

    Woodhouse reads the aggregate Bubbles serves from its cloud Worker at api.bubbles.loftwah.com; the game's cloud profile and score data stay in its own D1 database.

    Evidence: Woodhouse src/data/portfolio-analytics.ts; Bubbles src/cloud/routes/portfolio-analytics.ts; wrangler.cloud.jsonc

Authoritative public sources

What this review does not know.

  • This review did not test save migration across browsers or storage-pressure eviction.
  • Profile-sync conflict handling between two signed-in devices was not exercised.
  • The retention and aggregation rules behind the public analytics route were not re-verified beyond the endpoint itself.
  • No physical-device or assistive-technology test was performed for this profile.