On Migrainular’s Today screen, you can type sleep hours on the day card, then tap the water control. Sometimes the sleep field snapped back to empty. My first note in the issue was basically: server sync is too eager — maybe add a Save button like diary entries.

That diagnosis was half right about the feeling, and wrong about the mechanism.

The setup

Migrainular is local-first. Days and diary entries live in IndexedDB (Dexie). Edits mark a row pending, then a background sync pushes and pulls against the server using last-write-wins on client_updated_at.

The day card is meant to be fast when you are not feeling well: bump water, chip caffeine, toggle a preventive. Text fields like sleep and food auto-save on change. Diary attacks are different — you edit a form and hit Save. That difference matters.

We already had a guard so background sync would not overwrite an input while you were still focused in it. That helped with “typing while weather or sync refreshes.” It did not help with this bug.

The repro that lied

1. Type a sleep value.
2. Tap + water.
3. Sleep resets.

From the outside: you edited, something synced, the UI reverted. Classic “eager sync” story.

What actually happens on that tap:

1. Focus leaves sleep → change fires → patchDay({ sleep_hours }).
2. Click fires → patchDay({ water_intake }).
3. Both paths do a read-merge-write on the same day row.
4. The UI hydrates inputs from whatever lands in IndexedDB after the write.

Those two patchDay calls race.

The real bug

saveDay looked innocent:

1. Load the current day from IndexedDB.
2. Merge in a partial patch (sleep_hours or water_intake).
3. Write the whole row back with a new client_updated_at.

If sleep and water both start from a snapshot where sleep is still null:

• Sleep write wins first → { sleep: 8, water: 0 }
• Water write finishes second from the stale snapshot → { sleep: null, water: 8 }

Sleep is gone. Sync then helpfully ships that loser to the server, and the hydrate effect paints the empty field, because by then you are no longer “typing” — you tapped a button. The typing guard correctly stood down. The data underneath was already wrong.

So yes, sync made the bad state visible and durable. It did not invent the bad state. The race lived on one device, in one database, between two partial writes.

The fix

I did not turn the day card into a Save button. Diary entries earn an explicit Save. Water taps should stay one-handed and cheap. The product constraint was: keep the fast path, stop losing drafts.

Two boring changes:

1. Serialize saveDay per day. Concurrent callers queue. Each write reads the latest row after the previous write finishes, so partial patches compose instead of clobbering.
2. Flush draft inputs before chip and button patches. Water, caffeine chips, preventives, and cycle toggles commit whatever is sitting in the sleep/food/etc. fields first, then apply their own update from that fresh day. Increments use a callback on the post-flush record so “+coffee” does not compute against a stale day while the input still shows a draft.

Sync still runs after saves. Hydrate still refreshes the form from the day record. Those are fine once the local write path stops racing.

What I’d look for next time

If a form field “resets after sync,” ask:

• Did two writes hit the same document with partial patches?
• Does blur plus click fire two async saves in the same gesture?
• Does the UI rehydrate from storage as soon as focus leaves the field?
• Is the “sync” step mostly amplifying a local loser?

Local-first apps blur the line between UI state, disk state, and server state. That blur is a feature until a race makes all three agree on the wrong answer.

Sync was not the bug. It was the messenger.

Try Migrainular at migrainular.com — pain, save, done.

The cheap click

A preset button looks like a link. On standby it is a link — pick Jazz, the board becomes Jazz. While live, the same click used to mean “tear down the hour and start another.” Queue gone. Generation bumped. Station ID again. OC ReMix into Rock felt like a bug even when it was intentional.

The product rule I wanted: browse is free; commit costs the hour. Listeners should be able to peek at Classical’s crates, flip to Hip-Hop’s dial chrome, and stay on Jazz until they mean it.

Two stations in one board

While On Air there are two names for “the station”:

• selected — what the transport is actually playing
• preview — what the dial is focused on

The UI reads a single dial:

export function dialStation(preview, selected) {
  return preview ?? selected;
}

Freq, name, theme, crates, and the share query follow dial(). The player, queue, and tab title stay on selected. That split is the whole design.

“Something is pending” is not only “preview ≠ selected.” Crate, order, library, and channel can drift from an AirSnapshot captured when the hour started. Same station, different crate — still Tune, still don’t kill audio yet.

export function browsePending(input) {
  if (!input.live) return false;
  if (input.previewId && input.previewId !== input.selectedId) return true;
  // …crate / order / library / channel vs air snapshot
}

On the live path, selectStation sets preview, re-renders the board, updates the URL, and returns. It never calls stop().

Discoverability is half the bug

Once browse was free, the next failure mode was quieter: people did not know how to finish the switch. The big On Air button hides while live (you are already on air). Confirm lived on a small lamp that only said Tune after you had already found the dial.

Two fixes:

1. Stations next to the lamp while live — opens the tuner fold and scrolls it into view. The fold label becomes “Stations” instead of “Presets.”
2. When browse is pending, #go comes back as Tune. Same control you used to start the hour.

.now.live:not(.tune-pending) #go {
  display: none;
}

State that only exists in a lamp is state nobody owns. Put the commit on the control people already trust.

Gotchas that came with the split

Share URL follows the dial. While you are previewing Classical, ?s= is Classical even though Jazz is still in the speakers. Track slug stays off the URL until you are not pending, so you do not pin Jazz’s song onto Classical’s link.

Cluster stations must not load into the airing queue from a preview. Calling loadCluster() from the dial focus while Jazz is live would mutate queue / index for the wrong mount. Preview paints channel lists; it does not become the bed.

Tab title stays honest to the air. The board can show Classical. document.title still names what you hear. That asymmetry is correct and a little weird until you expect it.

What it feels like

On Air. Tap Stations. Wander. The hour keeps going. When the dial is where you want it, hit Tune — then the generation flips and the new station ID runs.

Two variables. One button that means commit. A lot less “why did my song die when I was only looking.”

Try it on airshift.fly.dev — go On Air, open Stations, pick something else, then Tune when you mean it.

The fake visualizer is supposed to bounce the whole time. It looks like Winamp. Pausing it to “save” a YouTube hour was a non-starter. The work was: keep the bars moving, keep the buttons snappy, and still have a break ready when the song ends.

The freeze

Kokoro runs in the page, ONNX, same origin as the iframe. CPU inference on the UI thread is a freeze. The board stops. FPS drops. You click Skip and nothing happens until the model is done talking to itself.

WebGPU already leaves JavaScript. WASM does not, unless you ask ONNX Runtime to proxy the session into a worker. That is now the CPU path. Generate still takes a while on a laptop; the page no longer goes dead while it does.

On Air also warms the model instead of waiting for the first break to download it. Slow generates (about 400ms, or every generate with ?debug=1) show up in the booth log so I can see which device is actually winning.

FPS lives in the mast all the time. The meter pauses when the tab is hidden. That was the cheap way to stop arguing about whether the board felt stuck.

Breaks that do not wait on the internet

A full break used to wait on Genius, Wikipedia, Ticketmaster, weather, news. If a helper was slow, the song ended and the DJ had nothing.

The skeleton is local: backsell, station ID, frontsell. Those lines synthesize as soon as the current song starts. Facts, headlines, weather, and tour dates clip in only if they are already ready. If they are not, the break still happens. joinBreak is the whole policy: head, optional extra, tail.

Talk is the same idea. Punch T and you get the booth, not a spinner behind a fetch.

First paint and the next song

stations.json is not small. It used to load with the main module, so the first paint waited on every crate. Catalog is a dynamic import now. Presets hydrate when the JSON lands. The JSON files are still the source of truth for lookup-ids; they are just off the critical path.

YouTube was the bigger hitch. loadVideoById on the live iframe means the next track starts cold. There is a second mount, #player-next, sitting at opacity: 0 (not display: none, or YouTube will not buffer). When the current song starts, we cueVideoById the next id in the queue. When that id is due, we swap which iframe is live and hit play. Same-id play still resumes, so talk-with-bed does not jump to the standby video.

GPU when the browser has it

The architecture post said CPU was the default. That was the safe story. It was also leaving speed on the table.

If nothing is saved and navigator.gpu exists, Kokoro starts on WebGPU. A stored CPU choice still wins. We do not write localStorage until you touch the select, so a machine that cannot keep WebGPU honest is one click from WASM, and we will not overwrite that.

What it feels like

The bars keep going. The next YouTube hour is often already cued. The DJ still talks; it just does not freeze the board to get there. 91.3 Indie showed up on the dial the same night, which is unrelated and also the point of a station you leave on: new crate, same clock.

Try Airshift at airshift.fly.dev — pick a frequency, hit On Air, watch the mast.

Weather is optional. Pain still saves with no network. When you are online, Today can show conditions and stamp barometric pressure (plus humidity and temperature) onto the entry. Pressure is the useful bit. A falling barometer is something a lot of us already feel; the app counts it, it does not forecast.

At launch that snapshot came from OpenWeather, proxied through Phoenix so the API key never sat in the PWA. That worked. It also meant a Fly secret, a quota, and a cache whose whole job was “do not burn the free tier.”

Migrainular will not charge people. OpenWeather’s key was leftover vendor machinery for a free app.

Why Open-Meteo

Open-Meteo is a free weather API for non-commercial use. No key. You ask for coordinates and the variables you actually want. For us that is current temperature, humidity, weather code, sea-level pressure, surface pressure, and a few hourly pressure points so we can show the change over the next three hours.

Their free tier is 10,000 calls a day, 5,000 an hour, 600 a minute. They ask for CC BY 4.0 attribution. That matches a diary with no ads and no subscriptions.

The PWA still does not talk to Open-Meteo. Phoenix is the proxy. One Fly IP, one cache, diary contents never ride along. Privacy stays the same shape as launch: location in, a small snapshot out.

City and ZIP go through their geocoding API first. Device GPS skips that and sends lat/lon. The JSON we hand the client did not change, so Today, the stamp on an entry, and the barometer overlay on Trends kept working.

Not burning the free tier

OpenWeather trained us to cache. We kept that, and tightened the GPS path.

Weather models are kilometer-scale. A phone is not. If you cache on the raw float, every visit to Today is a new key and a real upstream call. We round to two decimal degrees (~1 km) before the cache key and the request. People in the same neighborhood share a slot. City and ZIP already did.

The rest is boring on purpose:

• About 20 minutes for conditions, a week for geocoding
• Only the fields we stamp, not a week of unused forecast
• A User-Agent that names the app
• No retries on a 500—the client can save the attack without weather

Dev stubs the upstream so local work does not hit them at all.

What you see in the app

If weather is still fetching, Today says it is checking. If it fails, it says it failed. It only asks you to set a city, ZIP, or device location when you actually have not. Privacy and Profile credit Open-Meteo.

That is the whole change: same 20-second log, same pressure stamp, no vendor key. Open-Meteo does the weather. Migrainular stays a diary.

Try Migrainular at migrainular.com — pain, save, done.

We do not run a flags SaaS. Auth is already magic-link email, so “who is this?” is on the request. The system is a table, an allowlist, and one check. That is not a flex about avoiding dependencies for its own sake. It is what Elixir and Phoenix are good at: the domain lives in a context, the UI is a LiveView, persistence is Ecto, and the same module serves the API. You can ship a working feature-flag system in an afternoon and it will feel like the rest of the app.

I wrote about the rest of the architecture separately; this is the smaller piece: turning a feature on for a few people without a deploy.

Why not the usual tools

The Elixir default is FunWithFlags: Ecto or Redis, ETS cache, groups, percentages, PubSub. LaunchDarkly (and Unleash, Flagsmith, and the rest) add targeting rules, client SDKs, and an audit trail. All of that is real product. We did not need it.

We have a small user base and a known list of testers. Percentages and anonymous actors are unused. A vendor SDK on web plus Android plus iOS is another integration to keep honest. FunWithFlags would have been the reasonable library choice; we still would have built Admin UI and wired checks to current_scope. For that amount of surface, a row and a function stayed smaller than adopting someone else’s model—and that is the interesting part. In a lot of stacks, “just build it” is how you get an unmaintainable snowflake. In Elixir, a context plus a schema plus a LiveView is the maintainable shape. The custom version looks like every other OnRotation feature.

Admin vs flags

Admin is not a feature flag. A config list of emails is who can open /admin and hit the admin API. That list changes rarely and should survive a bad database row.

Feature flags are for product. They live in Postgres, get edited from Admin (web, Android, or iOS), and answer: does this signed-in user get this experimental UI? Mixing the two would mean either redeploying to add a beta tester, or handing blog-admin to someone who only needed meal ideas.

The model

A flag has a unique name (ai_meal_ideas), an optional description, and allowed emails. There is no on/off switch, no percentage, no household targeting. Empty emails, or a name that is not in the table, means off. If we forget to create the flag, nobody sees the feature.

schema "feature_flags" do
  field :name, :string
  field :description, :string
  field :allowed_emails, :string
  timestamps(type: :utc_datetime)
end

Emails are a comma-separated string. A join table would be cleaner to query; a textarea we edit a few times a month does not need that.

The check is one function: given the caller’s scope (user + household) and a flag name, is this user’s email on the list? Comparison is case-insensitive. Missing user or missing flag is false. We look the row up when we need it. Caching can wait until a check is actually hot.

Where it gates

Call sites hide the UI and refuse the action. LiveView events are still reachable if you know the name, so the same predicate runs before we spend money or mutate data.

AI meal ideas is the live example. The feature also needs an AI backend configured (Gemini, Ollama, or OpenAI). Env says the machine can do it; the flag says which people may. Both have to be true:

defp meal_ideas_enabled?(socket) do
  scope = socket.assigns.current_scope
  MealIdeas.available?() and FeatureFlags.enabled_for_scope?(scope, "ai_meal_ideas")
end

That is the whole gate: a context function and a boolean. The LiveView, the event handlers, and the API can all ask the same question.

Native apps do not evaluate flags for end users yet. They do manage them: the admin API is the same context, not a second source of truth.

What we skipped

We do not do percentage rollouts—we know the emails. We do not evaluate flags on the client and trust the button; the server decides. Names are strings, not an enum, so shipping a feature to everyone is delete the row and grep the checks. Experiments are person-scoped even though meals are household-scoped. If we ever want a household in a beta, that is a new field, not more emails.

Adding a flag is: gate the code, create the row in Admin, paste emails. When it is done, delete the flag and the checks.

Textarea and Postgres is the right amount of machinery. The point is not that flags are easy. It is that Elixir lets a small team build the version that actually fits the product, keep it in the same codebase as the meals and the plan, and stop when it gets the job done.

Try OnRotation at onrotation.app — start with the Starter Pack and plan the week in minutes.

Playlists are the songs. A station is the space in between the music. That is the part Airshift is for.

What it is

Airshift is a personal web radio that lives in the browser. You pick a format, hit On Air, and it keeps going. The crate is how you pick an hour. The work is the space in between: station IDs, backsells, a fact, the bed ducked under the voice. Songs on most hours come from hardcoded YouTube lists in a visible iframe. Breaks duck the track instead of pausing it. The DJ reads canned liners, a Wikipedia or Genius fact, optional weather, and optional headlines.

There is no account. There is no YouTube Music login. Add it to the home screen if you want; Bluetooth lock-screen controls use Media Session. This is not Android Auto—the car sees whatever Chrome is playing.

The tuner

Presets are frequencies, not playlists:

• 88.3 Jazz through 103.5 Pop Hits, with 101.7 Rock as the default
• 90.3 The Wire — live mounts (KEXP, WWOZ, Jazz24, KUTX, Radio Paradise, Nightwave Plaza, KCRW Eclectic24, The Current, dublab, KXLU, WKCR)
• 89.7 OC ReMix — Rainwave’s video-game remix channels
• 104.7 Yours — paste video links or JSON onto the crate. Playlist URLs are not expanded on the public origin (that would be an open proxy).

Rock has subcrates (Classic, Grunge, Britpop, and so on) so you can park on one flavor the way The Wire parks on a city. Hits are the default library; Settings can swap the hour to deep cuts, or a mix. Shuffle is on unless you ask for in-order. The next YouTube hour avoids the last 12 songs on that station.

Keys: 1–9 presets, space pause, S skip, P prev, T talk, . end song.

The booth

The DJ is not a large language model making up a morning show. It is a clock: station IDs, frontsells, backsells, skip lines, time checks. Facts come from Genius when the sidecar has a token, Wikipedia when it does not. Weather is Open-Meteo. News is NPR, local, BBC World, or NPR Music.

Voice is either the browser’s speech engine or Kokoro running in the tab (ONNX, CPU by default, GPU if your machine likes it). Station intros are packed as WAV so On Air does not wait on the model. Uncached lines generate while a song plays, then they are ready when the break hits. If Kokoro fails, the hour keeps going on the browser voice.

Sleep timer fades the bed into Standby. Feedback in Settings goes to the booth.

Where it runs

airshift.fly.dev is the origin: phone, PWA, car. Playback is in the tab; Fly only has to serve the page and a few helpers, so scale-to-zero is fine.

A home box is still unsolved. I want the board on the LAN—always on, playlist URLs, maybe a custom news feed—without turning Fly into an open proxy, and without a self-signed cert that YouTube will not embed against. HTTPS at home, HTTP on the LAN, or something in between: that is next, not this launch.

I spend most of my product time in Phoenix LiveView. Airshift is not that. The hour has to keep playing while you lock the phone, and the DJ has to speak in the same tab as the iframe. The stack for that is in a follow-up.

Try it

Airshift is live at airshift.fly.dev. Pick 101.7, hit On Air, and leave the monitor visible on YouTube hours—some uploads refuse to embed and get skipped.

If a mount is dead or a videoId is wrong, send it through the feedback line. I listen to this thing too.

Why not LiveView

OnRotation is Phoenix LiveView. Migrainular is a Svelte PWA talking to a Phoenix API, because a migraine log has to save with no network.

Airshift is a third shape. Playback is client-owned. YouTube’s IFrame API, HTML5 audio for live mounts, Web Speech or Kokoro, Media Session, and a service worker all want to live next to the board. A LiveView socket cannot own that hour. Fly can sleep; the tab cannot.

So the app is a Vite + TypeScript SPA with vanilla DOM—no React, no Svelte. One main.ts drives the board. CSS is a single file with station themes as variables (Studio, Midnight, After Hours, and the rest). Tests are node:test with --experimental-strip-types.

Tech stack

• TypeScript ~7 and Vite 8
• vite-plugin-pwa (Workbox, Add to Home Screen)
• YouTube IFrame API for format hours
• HTML5 <audio> for The Wire and OC ReMix
• kokoro-js (Kokoro-82M ONNX in the tab) or the browser voice
• Node http server (scripts/serve.mjs) for dist/ plus a sidecar
• Fly.io (iad, shared-cpu-1x, 256 MB, scale-to-zero, force HTTPS)
• Simple Analytics for pageviews and station_play (no cookies, no song titles)
• Open-Meteo, Wikipedia, Genius (token on the server), RSS news

youtubei.js is a dev dependency for playlist-URL expand and lookup-ids. It is not on the Fly image.

Two transports

player.ts exposes one Transport: play, pause, seek, volume, times. Behind it:

1. YouTube — load the IFrame API, loadVideoById, skip on error (uploads that refuse to embed). The studio monitor has to stay visible; that is a YouTube constraint, not a UI flourish.
2. Audio — audio-player.ts wraps a single <audio> element. Live mounts get mirror URLs, a stall watchdog (~15s without a progress beat), and failover. Breaks duck volume instead of calling pause, so Icecast does not drop.

playSourceOf picks youtube vs audio from the track. The Wire and OC ReMix are kind: "audio" stations: channel strips, not song crates. You pick KEXP or Rainwave Chill and stay there. Now-playing for Rainwave and Nightwave Plaza is polled over CORS; no auth.

The clock

Stations live in JSON (stations.json, deep-cuts.json) plus a couple of code-defined strips (wire.ts, ocremix.ts). A track is a title, artist, optional year, and either a videoId or an audioUrl.

clock.ts is the crate logic:

• Subcrates on Rock (Classic, Grunge, Britpop, …) so one frequency can still park on a flavor
• Library — hits, deep cuts, or mix
• Order — shuffle or in-order
• Don’t-repeat — next YouTube hour avoids the last 8 / 12 / 16 on that station
• Legacy tuner ids migrated into Rock subcrates via localStorage

Yours 104.7 is a station whose crate you paste in (video links or JSON). Expanding a YouTube Music playlist URL needs youtubei.js. That stays off Fly on purpose.

The DJ

That in-between is the product. Liners are functions, not a prompt: station ID, frontsell, backsell, skip, time check, weather, news, a Genius or wiki fact. Copy is packed into baked-liners.json as WAV so the first ID does not wait on the model. npm run bake-liners rebuilds that after copy changes.

Kokoro runs in the page (onnx-community/Kokoro-82M-v1.0-ONNX). CPU/WASM is the stable default; WebGPU is faster on some machines and garbage on others. The voice files download from Hugging Face once and cache in the browser. Uncached lines (facts, weather, news) generate during the song, then play at the break. If the model fails, Web Speech takes over and the hour continues.

Duck the bed, talk, restore. Mute is a setting. Sleep timer (sleep.ts) fades gain into Standby.

Sidecar, not a backend

Production is still a static SPA. serve.mjs maps files from dist/, SPA-fallbacks unknown paths, and hands a few routes to sidecar.mjs:

• GET /airshift/news — allowlisted feeds (NPR / BBC / NPR Music / local place)
• GET /airshift/genius — token from Fly secrets
• POST /airshift/feedback — in-app note to the booth
• POST /airshift/error — client/server errors
• GET /airshift/playlist — 404 on Fly

The public VM is not an open proxy. Rate limit is 40 requests / minute / IP. Genius never ships the token to the tab. If news or Genius is down, the hour continues without that line.

PWA and the car

Workbox precaches the shell, skips WASM/ONNX blobs (those are huge), and treats /airshift/* as NetworkOnly. display: standalone, Apple meta tags, Media Session for lock-screen skip/pause. Chrome can Add to Home Screen from the HTTPS origin; iPhone is Share → Add to Home Screen.

Fly config is boring on purpose: auto_stop_machines = "stop", min_machines_running = 0. The first hit after sleep pays a wake; then you are in the tab and the VM can nap again.

What stays out of the tab

• Genius token
• Discord for feedback and crash notes (no crate)
• Playlist-URL expand (not on the public origin)

Analytics is Simple Analytics with Do Not Track respected. sa_event("station_play", { station }) is the only custom event. Song titles stay off the wire.

Still open: home

The board wants to live on the LAN too: always on, paste a playlist URL, maybe a custom RSS feed. The constraints fight each other. Fly cannot grow an open proxy. A self-signed cert on a home box breaks YouTube embeds. Plain HTTP on the LAN works for embeds and dies the moment you want a real PWA, geolocation, or Kokoro on a phone that is not on that Wi‑Fi.

There is Docker and a playlist flag in the repo. I would not call that a product yet. Next is a home origin that is trusted enough for YouTube and private enough for expand—without teaching the Fly VM to fetch arbitrary lists.

Summary

Airshift is a client radio with a tiny same-origin helper:

• Vite TypeScript SPA, vanilla DOM, CSS variables for the board
• YouTube iframe hours and HTML5 live mounts behind one transport
• Crate logic in clock.ts, liners in liners.ts, speech in speech.ts
• Kokoro in-tab with baked WAVs and a browser-voice fallback
• Fly for HTTPS / PWA; home still TBD

The lesson I keep relearning: put the process where the constraint is. For a meal plan, that is the server. For a diary during an attack, that is IndexedDB. For a station you leave on, that is the tab.

Try Airshift at airshift.fly.dev — pick a frequency and hit On Air.

That is the whole product. I spend 20 seconds or less filling out my diary entry.

Migrainular is a private migraine diary. It lives on your phone as a Progressive web app(PWA). Days and attacks save on the device first. Sync is optional, when you choose, so you can restore on another device or print something for a clinician. It is a personal tracker—not a diagnosis, not a treatment, not medical advice.

I already owned the name. There was an older Phoenix app under it that stored a handful of fields and was not a diary I would actually use during an attack. I started over.

The constraint

A useful attack log has to be completable in about 20 seconds. Pain level is the only required field. Everything else is a chip you can skip.

If you have logged before, Same as last time copies the previous attack—pain, location, aura, meds, symptoms—so you can glance and save. Notes, timing, and weather stay with this attack, not the last one.

The day card (sleep, water, food, caffeine, workout, CPAP AHI) is a different job. That is “when you have more energy.” It is not on the way to Save.

I have been ruthless about this. If a new field would make someone in pain think, it does not belong on the form.

What you can log

Attacks: pain 0–10, type, location, aura, skippable chips for nausea and light/sound/smell sensitivity, when it started, whether it is still going, and medications.

Medications are a library in Profile, not a pharmacy. You list what you take. Rescue meds can show as one-tap chips on an attack. A monthly preventive can stay on the list without appearing every time you log. Deletes sync across devices.

Days: sleep, water (glasses or ounces), food, caffeine, workout, and—if you use a machine—CPAP - AHI (events per hour), not a vendor 0–100 score.

Weather is optional. Conditions are proxied through Phoenix so the client never talks to the weather API. Barometric pressure gets stamped onto entries when you are online. Offline, you still save. We started on OpenWeather; we now use Open-Meteo.

Trends are on-device charts: pain over time, overlays for sleep, caffeine, barometer, and AHI. Export is CSV plus a printable provider summary, including your current medication list.

Sign in is a magic link. No password. Logout clears the diary on that device; sign back in and pull from your account. There is a Clear this device control if you lent someone a browser.

Why a PWA, not LiveView

I spend a lot of time in Phoenix LiveView—OnRotation is built that way, and I have written about making LiveView feel offline-ish. For a meal plan on the couch, a reconnect cache is enough.

For a migraine log, it is not. The save button has to work with no network, in airplane mode, with a flaky cell connection, after the tab has been killed. The client owns the write: IndexedDB first (Dexie), then a boring last-write-wins sync when you are online.

So Migrainular is:

• Svelte 5 PWA in web/ (Vite, service worker, Add to Home Screen)
• Phoenix JSON API for magic-link auth, sync, and the weather proxy
• Postgres on Fly, same neighborhood as OnRotation
• Dark by default. Low glare. No reminder nags.

Diary contents never go to analytics. If Simple Analytics is on, it is anonymous pageviews with Do Not Track respected. In-app feedback posts to Discord without the diary attached. Delete account deletes the server copy.

Try it

Migrainular is live at migrainular.com. Sign in with email, add it to your home screen if you want, and the next time it hurts: pain, save, done.

This post shows a small pattern to make a list (or any data-heavy view) feel “offline-ish”: cache a serializable snapshot in localStorage, have the client push it to the server in a follow-up event (not in connect params—that can blow the URI length limit), and show it immediately while still refetching in the background. If decode or staleness check fails, you fall back to a normal load.

I used this for the shopping list in OnRotation; the same idea applies to any LiveView that remounts often on mobile.

1. Cache shape

Store a JSON object with whatever the template needs to render, plus a timestamp for staleness:

• entries – array of items (e.g. id, display_name, quantity, category, checked, …)
• Any other assigns the template uses (e.g. selected_week_start, week_meal_names, item_key_to_meal_names)
• cached_at – ISO8601 timestamp so the server can ignore cache older than your TTL (e.g. 15 minutes)

Use a single key per origin (e.g. myapp_shopping_list) if you have one list per user.

2. Server: push cache after loading or updating

Whenever you assign the list (or related) data, push a serializable payload to the client so the hook can write it to localStorage. No structs or DateTime in the payload—plain maps and strings.

defp build_cache_payload(assigns) do
  %{
    "entries" => Enum.map(assigns.entries || [], &entry_to_cache/1),
    "selected_week_start" => assigns.selected_week_start && Date.to_iso8601(assigns.selected_week_start),
    "cached_at" => DateTime.utc_now() |> DateTime.to_iso8601()
    # ... other keys the template needs
  }
end

defp push_cache(socket) do
  push_event(socket, "cache_shopping_list", build_cache_payload(socket.assigns))
end

Call push_cache(socket) at the end of handle_info(:load_plan, socket) and after every handle_event that updates the list (toggle, add, delete, etc.).

3. Client: hook to write cache

A hook that listens for the event and stores the payload:

const CACHE_KEY = "myapp_shopping_list"

const ShoppingListCacheHook = {
  mounted() {
    this.handleEvent("cache_shopping_list", (payload) => {
      try {
        localStorage.setItem(CACHE_KEY, JSON.stringify(payload))
      } catch (_) {}
    })
  }
}

Mount the hook on an element in your LiveView (e.g. a hidden div so it’s present when the list is rendered).

4. Client: send cache in a follow-up event (not connect params)

Do not put the cache in LiveSocket’s params. Those end up in the connection URL and can hit URI length limits (often 4–8KB), causing “request URI too long” errors and even infinite redirect/error loops when the list is large.

Instead, have the same hook that writes the cache push an event to the server when it mounts. The payload goes in the WebSocket message body, so size is not an issue:

const ShoppingListCacheHook = {
  mounted() {
    this.handleEvent("cache_shopping_list", (payload) => {
      try {
        localStorage.setItem(CACHE_KEY, JSON.stringify(payload))
      } catch (_) {}
    })
    // Send cache to server in a follow-up event to avoid URI length limit
    try {
      const cached = localStorage.getItem(CACHE_KEY)
      if (cached) this.pushEvent("restore_cached_list", { cache: cached })
    } catch (_) {}
  }
}

Keep params: { _csrf_token: csrfToken } (or a simple static object); no cache there.

5. Server: apply cache when the event arrives

Handle the event: if you’re still loading and the cache is valid, apply it and set your loading flag to false. You still run the refetch (e.g. send(self(), :load_plan) in mount); when it completes, assign fresh data and call push_cache again.

@cache_ttl_seconds 900  # 15 minutes

def mount(_params, _session, socket) do
  socket = assign_defaults(socket)
  send(self(), :load_plan)
  {:ok, socket}
end

def handle_event("restore_cached_list", %{"cache" => cache_str}, socket) when is_binary(cache_str) do
  if socket.assigns.plan_loading? do
    case try_apply_decoded_cache(socket, cache_str) do
      {:ok, updated} -> {:noreply, assign(updated, :plan_loading?, false)}
      :skip -> {:noreply, socket}
    end
  else
    {:noreply, socket}
  end
rescue
  _ -> {:noreply, socket}
end

def handle_event("restore_cached_list", _params, socket), do: {:noreply, socket}

defp try_apply_decoded_cache(socket, cache_str) do
  case Jason.decode(cache_str) do
    {:ok, decoded} when is_map(decoded) ->
      if cache_fresh?(decoded), do: {:ok, apply_cached_assigns(socket, decoded)}, else: :skip
    _ -> :skip
  end
end

defp cache_fresh?(decoded) do
  case decoded["cached_at"] do
    nil -> false
    iso when is_binary(iso) ->
      case DateTime.from_iso8601(iso) do
        {:ok, dt, _} -> DateTime.diff(DateTime.utc_now(), dt, :second) <= @cache_ttl_seconds
        _ -> false
      end
    _ -> false
  end
end

Decode and apply: build entries (and any derived assigns like entries_by_section) from the decoded map. If anything fails (decode, missing keys, bad types), leave the socket as-is and let the refetch show the real data. No need for elaborate validation—fail fast and fall back.

Edge cases

• No cache – Behave as today: loading spinner, then load.
• Stale cache – Ignore if cached_at is older than your TTL; load as normal.
• Decode / structure error – Ignore cache and refetch. Defensive decode keeps bad or tampered data from breaking the view; the server remains the source of truth.

Security note

The cache is only for UX: show something immediately. The server always re-fetches and scopes data by the authenticated session. Don’t trust the cache for authorization. For a shopping list or similar, storing it in localStorage is fine; for more sensitive data, consider whether you want it on the client at all.

Summary

1. After each load or mutation, push_event(..., "cache_...", payload) with a serializable snapshot.
2. A JS hook writes that payload to localStorage and, on mount, reads it and pushEvent("restore_cached_list", { cache }) so the server gets it in a WebSocket message (not connect params—avoids URI length limits).
3. Server handles "restore_cached_list": if still loading and cache is valid (decode + TTL), apply it and set loading to false.
4. Mount always triggers a refetch; when it completes, assign fresh data and push the new cache.

With a short TTL (e.g. 15 minutes), users get an instant list when they reopen the app after a brief lock, and the list still refreshes in the background so it stays accurate.

For more on hooks and storage, see the earlier post Phoenix LiveView with localStorage or sessionStorage; this one focuses on reconnect/mount and sending the cache in a follow-up pushEvent (not connect params) to avoid both the full refetch and URI length limits.

Tech Stack

• Phoenix 1.8 with LiveView
• Ecto + PostgreSQL for persistence
• Tailwind CSS v4 for styling (CSS variables, no config file)
• Req for HTTP (no HTTPoison/Tesla)
• Resend for transactional email (magic links, invites)
• Sentry for error tracking

Quality tooling: Credo, Dialyzer, SoBelow (security), all wired into mix precommit.

Architecture Overview

The app follows a context-based structure. Core domains:

• Accounts – users, households, invites, magic-link auth
• Meals – meal library, curated meals, meal packs
• Plans – weekly plans and plan entries
• ShoppingLists – per-household shopping list with plan-derived items
• Blog – public blog with Earmark-based body processing

Almost all domain data is scoped by household. A user belongs to one household; meals, plans, and shopping lists are all keyed by household_id. That keeps queries straightforward and authorization simple.

The Scope Pattern

We use an OnRotation.Accounts.Scope struct to represent the caller’s context:

defstruct user: nil, household: nil

phx.gen.auth gives us current_scope, not current_user. The scope carries both user and household, so controllers and LiveViews can consistently pass current_scope into contexts. Context functions take scope or household_id as the first argument and scope all queries by household.

This avoids leaking user-only logic into contexts and keeps “who is acting” and “on which household” explicit.

Routing and Pipelines

We use separate pipelines and live sessions for different auth levels:

• Public – marketing, blog, sitemap, robots (browser_and_seo)
• Auth routes – log-in (magic link), registration
• Authenticated – plan, meals, shopping list, feedback (live_session :authenticated)
• Blog admin – create/edit blog posts (require_blog_author)
• Meal pack admin – manage curated meal packs (require_meal_pack_admin)
• Admin – metrics dashboard (require_admin)

The API pipeline (/api/v1) accepts JSON and uses Bearer token auth. It’s used by the Android app; web users stay in LiveView.

Authentication

We’re privacy-focused: no passwords, magic links only, and Simple Analytics for basic analytics instead of tracking-heavy alternatives. No cross-site tracking, no ad networks.

Web users sign in via magic links. The flow:

1. User enters email.
2. We create or find the user and send a tokenized link (Resend).
3. User clicks the link; we validate the token and establish a session.

For the mobile API:

1. Client calls POST /api/v1/auth/magic-link with email.
2. User receives the link and opens it in a browser; we redirect to a page that calls the API to exchange the token for a Bearer token.
3. Client stores the Bearer token and sends it on subsequent requests.

Both flows end up with a session token; web uses cookies, API uses Authorization: Bearer <token>.

Data Model

The main entities:

• Household – one per account; owns meals, plans, shopping list
• Meal – name, recipe_url, main_ingredients, extras, tags, complexity (1–3)
• Plan – one per week per household (week_start_date = Monday)
• PlanEntry – links plan to meal, with day_index (0=Mon … 6=Sun) and position for multiple meals per day
• ShoppingListEntry – per-household; entries come from plan merge or manual “extras”

Meals, plans, and shopping lists are always queried with household_id in the WHERE clause.

Shopping List: Plan Merge and Categorization

The shopping list has two sources of items:

1. Plan-derived – parsed from main_ingredients and extras of meals in the current week’s plan
2. Manual extras – user-added items (e.g. paper towels, milk)

merge_plan_into_list/2 takes the current week’s plan, parses ingredients into segments (comma/semicolon), normalizes them into item_keys for grouping, and upserts into ShoppingListEntry by (household_id, item_key). Existing rows are never deleted by the merge—only added or updated.

Categorization is done by ShoppingLists.Categorizer: whole-word keyword matching against produce, meat/seafood, cheese/dairy, pantry, and a default “items” bucket. Priority order matters (e.g. “egg noodles” matches pantry before cheese) so we can sort the list in a sensible shopping order.

LiveView and UI

Core features (plan, meals, shopping list) are LiveView pages. We use:

• Streams for large, appendable lists to avoid memory growth
• Functional components (CoreComponents) for forms, buttons, layout
• Colocated JS hooks when we need client behavior (e.g. theme toggle in localStorage)

All LiveView templates start with <Layouts.app flash={@flash} ...> and receive current_scope from the live_session so they can pass it into context calls.

Design System

Colors and typography live in DESIGN.md and CSS variables (var(--onrotation-primary), etc.). Light/dark themes use data-theme="light" and data-theme="dark"; we also support “system” via prefers-color-scheme. Theme choice is persisted in localStorage and applied before paint when possible to avoid flash.

Transactional emails share the same layout and brand colors, with inline styles for email client compatibility.

Blog and Content

The blog is a separate context (OnRotation.Blog) with published posts, tags, and an author-scoped admin. Body content is stored as Markdown in the database and rendered with Earmark at request time. A BodyProcessor runs after Earmark to replace {{meal:N}} shortcodes with rendered meal cards—so authors can embed curated meals in posts, and logged-in users can add them to their library in place.

The blog admin is a LiveView (BlogAdminLive) behind a require_blog_author plug. Authors get a list view, create/edit with autosave draft, tag management, and a preview that matches the public layout. Public routes are controller-based: index (optionally filtered by tag), show by slug, and an RSS feed at /blog/feed.xml. The sitemap includes blog posts for SEO. Slugs are derived from titles; tags are many-to-many and filterable on the index.

API for Mobile

/api/v1 exposes resources for meals, plans, and plan entries. The API uses the same context functions as the web app; the only difference is auth (Bearer tokens) and response format (JSON). A plug assigns household_id from the authenticated user so controllers can call contexts like Meals.list_meals(household_id, opts) without extra logic.

Quality and Consistency

We enforce consistency with:

• One alias per line – no alias Foo.{Bar, Baz}
• @moduledoc and @spec on public functions
• No maybe_ prefix – use descriptive names instead
• mix precommit – format, Credo, SoBelow, Dialyzer, tests

The AGENTS.md and .cursor/rules files document these conventions for humans and AI-assisted workflows.

Summary

OnRotation is a Phoenix app where:

• Household-scoped contexts and a Scope struct keep authorization and data access clear.
• LiveView drives the web UX with streams and functional components.
• A small JSON API under /api/v1 serves mobile with the same business logic.
• Magic links power both web and mobile auth.
• A token-based design system and precommit checks keep the codebase consistent and maintainable.

If you’re building something similar—household/multi-tenant, LiveView-heavy, with a mobile API—this architecture is a solid starting point. The main lesson: invest in scoping and context boundaries early; they make everything else easier.

Try OnRotation at onrotation.app — start with our Starter Pack and plan your week in minutes.