How fresh the data is
Nothing in Sunset Beach is fetched live when you open the app. A cron job on the Worker runs every 5 minutes, refreshes every upstream whose cache has expired, and publishes one assembled copy of the conditions that every phone and browser then reads. So a reading is at most its source’s cache lifetime plus up to two cron ticks old — for the buoys that means roughly 5–15 minutes, for tides up to 6 hours (they are predictions, so it doesn’t matter), and for a fishing report up to an hour. When an upstream is down, the Worker serves the last copy that worked and labels it — “Cached” on the Sources screen, “Showing last good reading” in the row’s detail — rather than showing nothing or passing old data off as live.
The pipeline, end to end
Section titled “The pipeline, end to end”In prose: the cron fetches each upstream through the same code path a reader would, honouring that source’s cache lifetime; a successful fetch is stored in the edge cache and also written to KV as the last-known-good copy; the cron then assembles the whole conditions payload once and publishes it to KV, and every request serves that copy verbatim. If an upstream fails or returns something unparseable, the KV copy is served in its place, flagged as stale with a reason. The widgets read a much smaller summary, built from the same cached sources and reused for up to a minute; a widget asks for it about every 30 minutes (10 after a failure), and iOS may space that out further.
How often each source is refreshed
Section titled “How often each source is refreshed”The lifetime is set by what the upstream actually does. The full per-source table is on Where every number comes from; this is the shape of it.
| Source | Refresh | Why |
|---|---|---|
| NWS active alerts | 2 min | safety feed |
| NDBC buoys 41024, 41013, 41110 | 5 min | stations post every ~10 min |
| NWS gridpoint forecast | 10 min | amended forecasts show up quickly |
| Springmaid Pier surge, BirdCast bucket listing | 10 min | 6-minute and 10-minute upstreams |
| Open-Meteo sky, marine; surf zone forecast index; coastal waters index | 15 min | hourly models, products issued a few times a day |
| Surf zone forecast product, air quality | 30 min | |
| eBird, pier fishing report, tropical outlook, sewer spills, coastal waters product | 1 h | |
| Town calendar ICS, shellfish closures, right whale slow zones | 3 h | |
| Launch Library 2 | 4 h, or 5 min while a visible launch is within T−75 to T+20 min | rate-limited upstream; the short window is what lets a slip reach a Live Activity |
| Tides, turtle counts, water quality, iNaturalist recent, proclamations, nest-database canary | 6 h | deterministic or slow-moving |
| Pier concert page, seasonal whale zones | 12 h | |
| Sound Waves page, iNaturalist species counts | 24 h | |
| OBIS, iNaturalist megafauna, BirdCast objects, shellfish classification | 7 d | historical, immutable, or a standing category |
| Right whale critical habitat | 30 d | a 2016 regulatory boundary |
The published conditions copy
Section titled “The published conditions copy”The conditions the app loads are not rebuilt per request. The cron assembles them once per tick and publishes the result to KV; readers get that copy until it is 10 minutes old (twice the cron cadence, so an ordinary KV lag never forces a rebuild), after which a request recomputes it. A refresh that finds nothing new costs the phone almost nothing, because it only checks its saved copy is current. The practical effect: the interpolated tide height, countdowns and the sun’s position can lag by up to two ticks, and the app’s Updated … time tells you exactly when the copy was built.
What “Cached” and “last known good” mean
Section titled “What “Cached” and “last known good” mean”Every fetched panel carries whether it is live, when it was fetched, and, if it fell back, why. The app turns that into one of three states:
| Status | Sources row badge | Row detail | Meaning |
|---|---|---|---|
| Live | (no badge, shows how long ago it was fetched) | “Live” | The upstream answered inside its refresh window. |
| Cached | ”Cached" | "Showing last good reading”, with a “Showing cached data because” line giving the reason in a plain sentence, such as “The source is limiting how often we can ask (HTTP 429).” | The upstream failed, timed out, rate-limited, or returned something unparseable, so the previous good copy is shown. Its fetched time is when that copy was fetched. |
| Down | ”Unavailable" | "Unavailable”, with an “Error” line | No usable copy exists — the panel shows nothing. |
The Sources screen (More › Sources) opens with a strip counting Live / Cached / Down out of the total, then “Updated <time>. “Cached” means a source failed, so the app is showing its last good reading.” The More tab carries the same tally in its Sources row (“N of M live”, with ”· N cached” and ”· N down” added only when non-zero). Tap a row for its detail, with View at the source. A few rows — Almanac, Parking, Beach rules & access, Ships offshore — are calculated or copied by the app itself and say so. What the app can’t measure at all is on More › Known gaps, not here.
How long a fallback may be shown depends on the source: 1 day unless the adapter says otherwise, and longer where a stale answer still beats none — 30 days for water quality, the pier report and the proclamations (the pier shuts for the winter, so a months-old report is the truthful answer), 7 days for launches and eBird. It is shorter where an old answer misleads: 3 hours for the surge anomaly (a day-old anomaly describes a different weather system) and 2 hours for NWS alerts. Past that window the panel goes to Down rather than showing something misleading.
The app’s memory
Section titled “The app’s memory”Separately from caching, the cron keeps a small diary: once an hour it writes a ~1 KB projection of the published payload (the verdict, the sunset rating and the cloud profile it came from, the rip level, water temperatures, the surge anomaly, the next tide, turtle counts, AQI, the pier’s catch list) to KV for 90 days, and once a day rolls the hours up into a record kept for two years, so the app’s forecasts can be compared with what the sky then did. Nothing on the phone reads this; it exists so the sunset and score weights can one day be tuned against outcomes.