Problem
Events live on the center’s website, built with a hosted website builder. On a phone it was hard to see what’s on tonight and what changed, and staff spent time on routine schedule emails. The center needed a system it could run without one volunteer.
Result / Impact
- Live since Monday 16 November 2026 (get the app (external site)). Everything runs on the center’s own accounts, documented in a written runbook; I completed the hand-over at launch.
- 48 seconds from a website edit to the app, in one measured run on the development environment.
- Staff edit in one place. The app and staff and study-program emails follow the website, with warnings about duplicate and overlapping events.
- Cheap to run, safe to change: isolated environments, tested releases, keyless deploys, a rollback path; it runs almost entirely on free tiers.
What I built
- One source of truth: a token-protected, read-only feed of the next 400 days; a save sends a data-free “something changed” signal.
- Copy only real changes, with a 5-minute safety-net check and twice-daily timers.
- Validate, then publish immutably: one adapter, typed contracts, an immutable snapshot plus a tiny manifest.
- Fast, offline phones: the app opens from on-device storage and fetches a snapshot only when the version changes; open apps hear within seconds, with a one-minute poll as backstop.
- Limited notifications: opt-in, only for cancelled or moved events, via anonymous device topics.
Reliability and security
- Fail closed: a bad or suddenly short feed publishes nothing; phones keep the last good schedule.
- Limits: if more than 10 notifications would go out at once, none are sent; admins get at most one problem email a day.
- Least privilege: each job has its own identity and secrets; the website reader cannot send email.
- Rollback: the last 20 releases, plus a kill switch for the offline worker.
- Privacy: no accounts, tracking or analytics (privacy page (external site)). Open security items are listed, not hidden.
Releases. Pull requests run linting, strict TypeScript, schema checks, unit tests and Playwright end-to-end tests on iPhone and Android engines with accessibility checks. Merging is the deploy, using short-lived, branch-bound tokens instead of deploy keys.
Measured before changing. When CI minutes ran low, I analysed every GitHub Actions run since 8 October 2026, modelled eight speed-ups and shipped the three that paid off.
Decision memos. Each design question got a memo with options, trade-offs and a recommendation; I made the call as lead developer. iPhone install guidance went through two rounds of scored layouts (winner: 92/100); light-mode event blocks measured only 1.02–1.07:1 contrast (dark mode about 1.4:1), so I chose a scheme that mirrors dark mode.
Directing AI-generated code. Built with Claude Code (Claude Opus 5.5) from a single-file prototype: I set the architecture, split each migration into steps owned by me or Claude, and reviewed every change through the pipeline. Planned: an incremental refactor with Claude Fable 5.2.
Tools: TypeScript (strict), pnpm workspaces, zod, React, Vite, IndexedDB, Workbox, Firebase, Google Cloud Run, Cloud Scheduler, Secret Manager, Workload Identity Federation, Gmail API, GitHub Actions, Vitest, Playwright, axe, Claude Code.
Decisions
The website stays the source of truth. Context: staff edit, and people register and pay, there. Options: an editable app copy; a read-only, validated copy. Decision: read-only. Consequences: nothing to reconcile; the pipeline fails closed on a bad feed.
Three isolated environments. Context: the system emails real people. Options: feature flags; shared data; fully separate. Decision: separate development, test and production, each with its own project, site, sender and lists. Consequences: tests can’t email members; three of everything to maintain.
Layered freshness, not push alone. Context: push isn’t guaranteed, and iPhones allow it only for Home Screen apps. Options: push; polling; a live channel with polling backstop and push for urgent changes. Decision: layered, each failure mode traced to a time-to-delivery. Consequences: more moving parts.
Hand over at launch. Context: a volunteer app can come to depend on its volunteer. Options: run it myself; hand over later; at launch. Decision: at launch, by runbook. Consequences: more work up front; the center controls its data and costs.