🏠 Family Hub

A no-build family wall dashboard — Google Calendar, keyless weather, shared shopping/to-do/budget, AI meal planning, chores and an ambient screensaver.

Setup guide · Feature reference · Easter eggs · Architecture notes

---

A wall-display family dashboard — calendar, weather, shopping, meals, chores and more — built as four plain files with no build step, no npm install, and no framework.

family-hub.html + family-hub.css + family-hub.js, plus hub-theme.css for the theme tokens. Drop them in a folder, serve them, done.

---

What it is

Family Hub is the screen that lives on the kitchen wall. It pulls in everyone's Google Calendars, shows the weather and the radar, keeps a shared shopping list that updates on every phone in the house at once, plans the week's meals, tracks chores, and fades into a screensaver when nobody's looking at it.

It's deliberately low-tech under the hood: CDN <script> tags (Firebase 9 compat + Google Identity Services), vanilla JS, CSS custom properties. There is nothing to compile — what you edit is what the browser runs.

Features

Calendar

• Month / Week / Day views over multiple Google Calendars, colour-coded and individually toggleable
• ICS subscriptions — subscribe to any public or secret .ics feed (school, sports, Outlook) with no Google sign-in at all; recurrence (RRULE/EXDATE/TZID) is expanded client-side
• Year at a Glance mini-month strip, countdowns, and conflict detection
• Recurring items (medications, trash and recycling, air filters, smoke alarm checks) on any every-N-days/weeks/months/years schedule, shown as their own calendar

Household

• Shopping list, to-do list and budget — shared in real time via Firestore, live on every device
• Meal planning with AI suggestions (Gemini), diet prefs and pantry awareness; accepted meals can push their ingredients straight to the shopping list
• Chore chart with family members and rotation
• Family Assistant — natural-language questions about the household's data

Ambient

• Weather — current conditions, forecast, RainViewer radar and NWS alerts, all keyless (Open-Meteo)
• Outdoor task advisor — scores the coming week's forecast against your calendar to pick the best window to mow the lawn
• Event discovery — nearby things to do, aggregated from Ticketmaster, library feeds, Red Wings, CitySpark and the Fairport/Pittsford town calendars
• Word of the Day, Dad Joke of the Day, quotes, news headlines and stock tickers as optional widgets, plus a set of easter eggs
• Google Photos background slideshow (photos cached as blobs in IndexedDB)
• Screensaver — photo slideshow, clock, or the Pond Chimes ambient pond, vendored in pond/

Presentation

• Themes: Auto (default, follows the device or sunset), Light, Dark, Accessible (colorblind-safe)
• Three themes (the material), independent of colors: Tactile (hand-made paper, the default), Glass (clear slabs), Paper (a flat printed planner); all fonts self-hosted
• Configurable widget placement and ordering on desktop; a registry-driven bottom-tab layout on phones
• Installable PWA with a network-first service worker, so the wall panel survives a flaky connection

Quick start

git clone https://github.com/mattohara42/family-hub.git
cd family-hub
python3 -m http.server 8080

Then open http://localhost:8080/family-hub.html.

⚠️ Opening the file directly (file://) will not work for anything Google-related — OAuth requires an http://localhost or HTTPS origin.

Weather, the word of the day and the jokes work immediately with no configuration. Everything else needs accounts — see family-hub-setup.md for the full walkthrough (Google Cloud OAuth client, Firebase project, API keys, authorized origins).

Deploying

Production runs on Netlify as a static site at familial.netlify.app, plus a handful of serverless functions:

Function	Purpose
netlify/functions/events.js	Event-discovery aggregation across several ticketing/library APIs
netlify/functions/ai.js	Gemini proxy — keeps the API key server-side
netlify/functions/ics.js	ICS feed proxy (CORS + SSRF-guarded)
netlify/functions/news.js	RSS/Atom proxy for headline feeds

Publish directory is .; the build command (node netlify-build.js) stamps a fresh cache version into sw.js so each deploy invalidates the old service-worker cache, and writes config.js from env vars when they're set (below).

Backend keys are set as Netlify environment variables — GEMINI_KEY, TICKETMASTER_KEY, OWM_KEY. Client-side config (Firebase, Google OAuth client ID) lives in config.js. A fork running its own Google/Firebase projects sets GOOGLE_CLIENT_ID and FIREBASE_CONFIG on Netlify instead of editing that file; see family-hub-setup.md.

Any new serving origin must be added to Google Cloud Console → Authorized JavaScript Origins and Firebase Console → Authorized Domains, or sign-in silently fails.

Project layout

family-hub.html        markup + CDN script tags (no inline CSS/JS)
hub-theme.css          theme tokens: fonts, palettes, material tokens (loads first)
family-hub.css         all other styling — layout, components, theme structure
family-hub.js          all logic + the config block at the top
config.js              Firebase + Google client ID (rewritten from env vars on deploy)
manifest.json  sw.js   PWA manifest and service worker
firestore.rules        Firestore security rules (auth-gated)
netlify.toml           headers, redirects, CSP-adjacent config
netlify/functions/     serverless backends
pond/                  vendored Pond Chimes screensaver (git subtree — don't edit in place)
tests/                 node --test unit tests
docs/                  brainstorms, plans, prototypes

Tests

npm test        # node --test tests/*.test.js

Covers the Netlify functions (event-discovery aggregation, recipe scraping, Home Assistant) and the browser app's pure helpers (the event date/time shift, the outdoor-task scorer, meal images). Function tests import the real code through its _test export; browser-app tests cannot — family-hub.js is a no-build monolith with nothing to require — so each of those carries its own copy of the function it exercises, and the two must be kept in sync. See BACKEND_TESTING_SETUP.md for running the functions locally.

Documentation

Doc	What's in it
FEATURES.md	The reference map — every feature's functions, state, HTML anchors and storage keys
family-hub-setup.md	End-user setup: accounts, keys, origins, step by step
CLAUDE.md	Architecture invariants and known gotchas (read this before changing anything structural)
EVENT_DISCOVERY.md	Event discovery design and API details
RETROSPECTIVE.md	Lessons learned along the way
EASTER_EGGS.md	The phrase cheat sheet
*_BACKLOG.md	Per-area backlogs — weather, meals, assistant, screensaver, easter eggs

Contributing

The architecture invariants in CLAUDE.md are the house rules: no build tooling, CSS stays in the CSS file, pond/ is vendored and updated only via git subtree pull, and mobile tabs are registry-driven rather than hand-written per card. There's a feature checklist there too.

License

MIT © Matt O'Hara.

The vendored pond/ subtree is Pond Chimes, also MIT, and carries its own LICENSE. Third-party CDN libraries (Firebase, Google Identity Services, Tone.js) remain under their own licenses.