Systems
Inside Mirai Guide: an offline-first event companion
How a loginless PWA, two Workers, and one hard rule about data keep a fan-run event guide trustworthy.
Mirai Guide is a trilingual, offline-first companion for Vocaloid concert events. Venue goods, crowd-reported stock and queues, a persistent local cart, maps, route planning.
It is also a one-person fan project that people rely on while standing in a hall with no signal and a limited amount of time. That combination is the thing I keep designing around, and this note is about the decisions that came out of it.
Two Workers, One Boundary
- The attendee PWA, the admin UI, and the HTTP APIs are a SvelteKit and TypeScript application on Cloudflare Workers.
- A separate pipeline Worker built on Cloudflare Workflows owns everything that touches the outside world: polite fetches of approved sources, extraction, translation, media caching, and proposal staging.
- D1 stores reviewed structure, catalogs, live state, passkey credentials, provenance, conflicts, and an append-only audit history. A private R2 bucket stores immutable published bundles, plus reviewed and content-hashed copies of product images from approved sources.
Attendees never log in. The app installs as a PWA and keeps working offline inside the venue from the published bundle. Only the owner and admin area authenticates, and that uses passkeys.
The Binding-Data Rule
This is the rule I care about most, and it is easy to state:
The repository, migrations, application code, tests, and documentation contain no event facts. No edition names, venues, days, vendors, booths, goods, or source URLs. D1 starts empty.
An administrator configures a public discovery URL. The extraction system proposes structure with evidence and confidence. A human reviews that proposal before any row exists.
What that buys:
- The same system supports future events with unknown names, cities, venue layouts, and booth numbering schemes, because nothing is hardcoded.
- IDs are opaque and classification keys are open strings with safe presentation fallbacks. Code never maps a vendor name to special behavior.
- Model output never publishes itself. Every proposal passes a human veto.
The tempting shortcut here is obvious. Hardcode this year’s venues, ship faster, clean it up later. But the cleanup never happens, and the next edition arrives with a layout nobody predicted.
Why This Shape
An event companion earns trust exactly once.
Splitting the data plane into reviewed structure, immutable published bundles, and clearly-labeled crowd reports means an attendee standing in a dead zone still has a working map and catalog. And nothing they are looking at was ever written directly by a crawler or a language model.