Architecture
Overview
Home Hub is a tablet-first PWA built with Vite. The UI is organised in three layers:
- App Shell — layout, system status, routing, and navigation
- Applications — user-facing destinations (Controls, House Guide, …)
- Widgets — reusable UI blocks used inside applications
App Shell
│
├── Home (launcher)
├── Controls App
│ └── Alexa Widget
├── House Guide App
│ └── House Guide Widget
├── Scooter App (placeholder)
├── Weather App (forecast via Worker)
├── Bins App (static council calendars)
├── Calendar App (placeholder)
└── Settings App (configuration)An App represents a user task (“Control the house”, “Read the guide”). A Widget is a reusable component with no knowledge of other apps. The product identity is Home Hub (Lovely Home Hub in chrome copy)—a coherent platform, not a single-purpose dashboard.
Navigation philosophy
- Always know where you are: persistent chrome shows a Home button and the current destination title.
- One tap home: Home returns to the launcher without reload.
- Focus by destination: each app owns the full viewport; unrelated widgets are not stacked on one scrollable page.
- Calm transitions: the viewport fades/slides slightly when routes change (CSS only, no framework router).
App Shell
Location: src/shell/
The shell owns:
- Persistent chrome (Home button, destination title, clock)
- Home-only welcome line (greeting + date) and status strip
- Viewport (
#app-viewport) where the active app mounts - Client-side routing (
src/shell/router.js, hash routes#/controls, …) - Profile change reactions (rebuild Home launcher immediately)
Start-up
src/js/app.js shows the full-screen "Opening your hub…" overlay (src/shell/startupLoadingOverlay.js: text, progress bar, and a "still opening" line after six seconds) until the shell can draw. Before that it needs four answers from the Worker, which src/shell/hubStartupRequests.js asks for all at once (#1386):
| Request | Used for |
|---|---|
GET /api/hub-suspension | Operator suspension notice (#844); stops start-up when suspended |
GET /api/device-session | Owner / sitter / guest mode, audience, hub name |
GET /api/hub/plan-features | Free vs Plus feature flags (the Worker asks the platform) |
GET /api/site/profile | Site profile, tablet preferences, setup state |
Each one is a round trip through the Pages Function proxy to the Worker, close to a second on a live hub, so asking in sequence used to add up to several seconds. None depends on another's answer (same cookies on every request; a rotated sitter cookie stays valid until it expires). The answers are still applied in the old order: suspension gate, then device session, then plan features, then profile and tablet preferences, then createAppShell. Keep it that way when adding a start-up request: start it in beginHubStartupRequests, await it where its answer is applied.
The main script holds English only, plus everything every audience uses. Each other language, pdf.js and the emoji picker are separate chunks fetched when needed (#1390, see hub-i18n.md). When adding a dependency only owners or only one feature needs, load it with import() where it is used, as src/lib/pdfjs.js does.
Application metadata
Apps are declared with defineApp() (src/components/App/defineApp.js) and registered in src/services/appRegistry.js.
Each app exports metadata rather than hardcoding Home cards:
| Field | Purpose |
|---|---|
id, title, iconId | Identity and Lucide icon (src/components/icons/renderIcon.js) |
description | Accessibility / future search |
capabilities | Tags for future search, voice, automation, AI (not all used yet) |
profiles | Who can see the app on Home |
accent | Card theming |
summary(context) | Optional live card data on Home |
mount(viewport, context) | Full-screen app UI |
Example capabilities: Controls → lighting, heating, scenes; House Guide → search, offline, quick-actions, home-info.
Application summaries
Optional summary(shellContext) returns { title, subtitle? }. Home cards render this as live information (e.g. routine count, weather snapshot, “Coming Soon”). Summaries are async-capable; the launcher fills cards after mount.
Weather summaries read src/services/homeWeatherSnapshot.js, updated when the status strip weather service loads.
Settings application
src/apps/Settings/SettingsApp.js — configuration for appearance, guest mode (owners), and weather location (owners).
Owners see:
- House sitter mode — enable or return to guest lock (server cookie)
- Appearance — theme (dark / light / auto), clock (12h / 24h), home screen size (zoom)
- Weather location — UK postcode or place lookup (
GET /api/weather/geocode); optional override stored inlocalStorageand passed as?lat=&lon=on weather requests - About — version, build, device mode, theme, clock, home scale, weather label
House sitters see Settings in the bottom nav (fourth tab). They get Appearance and About only — no guest-mode or weather-location controls.
Display preferences persist in the browser (themeService, displayPreferencesService, weatherLocationService):
| Preference | Storage key | Applies to |
|---|---|---|
| Theme | home-hub-theme | Whole app (data-theme on the document root element) |
| Clock format | home-hub-clock-format | Header clock via formatTime() |
| Home screen zoom | home-hub-home-scale | .home-screen via CSS zoom (0.9–1.2) |
| Weather location | home-hub-weather-location | Weather API query override |
Device sitter mode (owner vs guest) remains server-authoritative via the sitter cookie — not a Settings profile toggle.
Applications
Location: src/apps/{Name}/
Each app folder contains:
{Name}App.js—mount(viewport, shellContext)and app metadataindex.js—registerApp()side effect
src/apps/index.js loads every app via import.meta.glob('./*/index.js', { eager: true }).
| App | Role |
|---|---|
| Home | Default launcher (renderHomeScreen); not registered in the app registry |
| Controls | Mounts the Alexa widget (Virtual Buttons) |
| House Guide | Mounts the House Guide widget (interactive home topics, search, quick actions) |
| Settings | Appearance, guest mode (owner), weather location (owner), about |
| Weather | Forecast and insights via Worker (GET /api/weather) |
| Bin Collection | Static Calendar 17 + Round G2 schedules, offline |
| My Day | Personal agenda via Worker ICS feed; optional per audience in Settings → People |
| Others | Focused placeholders with summaries where useful |
Apps declare profiles: ['owner', 'housesitter'] (or subsets). getAppsForProfile() drives the Home launcher cards.
Widgets
Location: src/widgets/{Name}/
Widgets register through src/widgets/index.js (same glob pattern as apps). The Controls and House Guide apps call getWidgetById() and mount the widget into their viewport.
Widget contract: src/types/widget.js, defineWidget().
Network access uses src/api/ — widgets and apps do not call fetch() directly.
Profiles
src/services/profileService.js — active profile defaults to owner. Home launcher and future app visibility are profile-filtered.
Deployment mode and user mode
Two independent concepts live under src/auth/:
| Concept | When set | Purpose |
|---|---|---|
| Deployment mode | Build time (VITE_DEPLOYMENT_MODE) | What the build allows |
| User mode | Runtime (in-memory) | What the UI shows now |
Deployment mode
src/auth/deploymentMode.js — home (default) or house-sitter.
home— Full hub tablet. Defaults to owner user mode. Owner and house sitter user modes are switched via device session (Settings guest lock and owner PIN gesture), not a profile picker.house-sitter— Dedicated guest deployment. Always house sitter user mode. Owner mode cannot be entered; hidden gesture does nothing.
User mode
src/auth/userMode.js — owner or house-sitter. Drives src/modes/modeConfig.js (branding, launcher apps, bottom nav, simplified controls).
getVisibleApps() in src/services/appVisibility.js remains the single entry point for Home cards and allowed routes.
Owner authentication (home deployment)
Hidden access for house sitter → owner (clears the sitter lock cookie):
- My Day: tap Enter owner PIN in the app, or
- Long-press the “Lovely Home” title block for five seconds (when the tablet is in house sitter mode).
Long press → PIN pad (`src/components/OwnerAccess/ownerPinDialog.js`)
→ ownerAuthProvider.authenticate(pin) (`src/auth/OwnerAuthProvider.js`)
→ POST `/api/auth/owner` on the Cloudflare Worker (clears sitter cookie)
→ owner user mode + owner profileNever use VITE_OWNER_PIN. Vite env vars are compiled into the browser bundle. The owner PIN must exist only as the Worker secret OWNER_PIN (npx wrangler secret put OWNER_PIN in the Worker project).
| Response | Meaning |
|---|---|
HTTP 200 { ok: true, authenticated: true, mode: "owner" } | Sitter lock cleared; owner mode |
| HTTP 401 | Wrong PIN (generic message in UI) |
| HTTP 429 | Rate limited (Durable Object tracks failures per client IP) |
| HTTP 503 | Worker secret not configured |
Rate limiting: OwnerAuthLimiter SQLite-backed Durable Object (OWNER_AUTH_LIMITER binding) stores failed attempts per client key. More than five failures within ten minutes returns HTTP 429 until the window expires or a successful login clears the counter. The Worker migration uses new_sqlite_classes (required on the Workers free plan).
Inactivity lock: OWNER_INACTIVITY_TIMEOUT_MS (five minutes) in src/auth/ownerInactivity.js auto-locks via lockToHouseSitterMode() — same path as Return to House Sitter Mode in Settings. This issues a sitter cookie on the server.
Cloudflare configuration
| Surface | Variables |
|---|---|
| Pages (frontend) | VITE_DEPLOYMENT_MODE=home, VITE_API_BASE_URL=https://{worker-hostname} |
| Worker (secrets) | OWNER_PIN — not Pages, not git, not wrangler [vars] |
House sitter experience (guest UI) is unchanged; owner experience is unchanged when user mode is owner.
The Emergency app (src/apps/Emergency/) surfaces call cards and deep-links into House Guide topics without duplicating catalog content.
House Guide
The House Guide is an interactive companion for living in the home—not a document viewer. The UI never exposes storage format, page counts, or other implementation details.
Layering
House Guide Widget (presentation)
↓
Guide Service (`src/services/guideService.js`)
↓
Content Provider (adapter)
↓
Structured JSON today · Markdown/PDF/API laterStructured content model (v2)
House Guide
↓
Categories (Arrival, Kitchen, …)
↓
Topics (Hot Water Machine, Heating, …)
↓
Blocks (text, steps, tip, warning, heroImage, gallery, …)
↓
Actions (Alexa, panel, navigate)
↓
Media (images under src/content/houseguide/media/)- Guide Service — facade:
listGuideCategories,getGuideCategory,getGuideTopic,searchGuideTopics,getGuideHomeSummary. - Content Provider —
jsonGuideProvider.jsreadsguide-catalog.json(version 2). Legacy.mdfiles are not rendered; usenpm run guide:extractafter addingsource/house-guide.pdf. - Blocks — composable content types in
src/types/guideContent.js. Hero and gallery blocks resolve images viaguideMedia.jswhen files exist inmedia/.
Protected house-specific values
Public guide copy lives in guide-catalog.json. Values that must not ship in public source control use protected blocks with dot-path keys resolved from private-content.local.json (gitignored). Copy private-content.example.json to private-content.local.json on a trusted device.
When keys are missing, the UI shows safe placeholders (for example Wi-Fi details when the stay or sit starts) — never undefined, empty buttons, or broken QR codes.
Production: Cloudflare Access and the Worker GET /api/private-config path (see cloudflare-access.md) serve protected values at runtime, not from the static Pages bundle. Owners turn on Settings → Sitter is here when a sitter is staying so those values appear in House Guide protected blocks on the sitter tablet.
Content pipeline (PDF not served in-app)
source/house-guide.pdf → npm run guide:extract → normalise into guide-catalog.json + contextual media/ files → application.
Navigation
Users browse areas of the home (categories), then topics (appliances, systems), then block-based detail pages—not document sections or page numbers.
Quick actions
Topic-level actions in JSON; executed by guideActions.js (Alexa virtual buttons, detail panels, cross-topic navigation).
Search
Concept search across categories and topics with aliases (e.g. kettle / tea → Hot Water Machine; Netflix → TV & Entertainment).
Presentation
- Landing — category cards for house areas.
- Category — topic list within that area.
- Topic — blocks + optional Quick Actions.
- Home card — meaningful summary strings, not document counts.
Legacy Markdown under src/content/houseguide/*.md remains optional source material until extraction fills the catalog.
Intelligent weather
Weather is Worker-only. The dashboard never calls Open-Meteo (or any other provider) from the browser.
Weather app + status strip + home card
│
▼
GET /api/weather (Cloudflare Worker)
│
├── 15-minute in-memory cache (`worker/src/weather/weatherCache.js`)
├── Provider abstraction (`WeatherProvider` / `OpenMeteoProvider`)
├── Mapping to stable JSON (`mapOpenMeteo.js`)
└── Rule-based weather insights (`adviceEngine.js`) — informative tone (may/might/could/consider); not safety directives (those belong in House Guide)
│
▼
Open-Meteo forecast + air-quality APIsHome location defaults to the Worker (HOME_LATITUDE, HOME_LONGITUDE in worker/wrangler.toml [vars]). Owners may override per tablet in Settings (postcode or place name); the override is stored in localStorage and sent as optional ?lat=&lon= on GET /api/weather. Lookup uses GET /api/weather/geocode?q= (UK postcodes via postcodes.io, place names via Open-Meteo geocoding).
Frontend: src/services/weatherService.js refreshes every 15 minutes and on startup; src/apps/Weather/WeatherApp.js renders current conditions, hourly/daily forecasts, and insights; Lucide icons via src/weather/renderWeatherIcon.js.
Offline / upstream failure: If Open-Meteo is unreachable, the Worker serves the last cached payload when available; the UI shows age labels (Updated N minutes ago) and a graceful unavailable state when no data exists.
Bin collection
Household and garden waste dates come from static data, not runtime council fetches. PDFs are transcribed once into src/data/binCollections/.
Data files
| File | Role |
|---|---|
householdCollections.js | Calendar 17 — { date, type: 'rubbish' | 'recycling', bankHolidayChange } |
gardenWasteCollections.js | Round G2 — { date } only |
collectionTypes.js | Display names, bin descriptions, icons, garden-waste allowed/not lists |
Metadata on each schedule includes validFrom, validUntil, source, and calendar/round id. The UI treats the calendar as expired only when no collection dates remain on or after today — a stale validUntil must not hide dates the owner has already added.
Service
src/services/binCollectionService.js merges household and garden events, compares local calendar dates only (parseLocalDate, startOfLocalDay), and exposes:
getNextCollection,getUpcomingCollections,getNextHouseholdCollection,getNextGardenWasteCollectiongetDaysUntil— Today / Tomorrow / In N daysgetBinCollectionHomeSummary— Home card copy (owner vs house sitter via options)
Future schedules could swap the data import for a Worker or council API; apps should consume the service API only.
Bank-holiday exceptions
Calendar 17 lists non-Friday collections with bankHolidayChange: true (e.g. Tue 30 Dec 2025, Tue 6 Jan 2026, Mon 12 Jan 2026, Sat 17 Jan 2026). These are stored as printed — not normalised back to Friday.
Maintenance
See bin-collection-maintenance.md for the exact files to edit when a new PDF arrives.
UI layout and screenshot maintenance: bin-collection-ui.md.
Device mode (House Sitter vs Owner)
Two independent security layers protect a shared household device (often a wall tablet):
| Layer | Question | Mechanism |
|---|---|---|
| Cloudflare Access | Who may reach the site? | Mark and Donna’s approved emails + emailed OTP |
| Device mode | What may this tablet show and call? | Signed HTTP-only cookie issued by the Worker |
Cloudflare Access stays enabled for the whole site. A valid Access session is required for every visit. Owner Mode is the default once Access succeeds.
Signed device session cookie
- Name:
lovely_home_device_session - Attributes:
HttpOnly,Secure,SameSite=Strict,Path=/ - Signing: HMAC-SHA256 over a base64url JSON payload using Worker secret
OWNER_SESSION_SECRET - Authority: The Worker validates the cookie on every protected route. React state,
localStorage, andsessionStorageare never authoritative. - Default: Missing cookie → Owner Mode (no cookie is issued automatically)
- Sitter lock: Only a deliberate, valid sitter cookie restricts the tablet to House Sitter Mode
- Invalid/expired/tampered sitter cookie: Cleared and treated as Owner Mode
Durations:
- House Sitter Mode — ~30 days (renewed on use when past half TTL)
- Owner Mode — no device cookie required (Access + owner identity only)
Session JSON responses use Cache-Control: no-store and never expose cookie bytes or signing material.
API endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /api/device-session | Current mode (owner unless valid sitter cookie) |
| POST | /api/device-mode | { "mode": "sitter" } — Access owner only; issues sitter cookie |
| POST | /api/auth/owner | PIN clears sitter lock → Owner Mode |
| POST | /api/auth/lock | Issues persistent sitter cookie (same as Enable House Sitter Mode) |
Owner-only routes (/api/private-config, owner PIN endpoint, …) require Cloudflare Access owner identity and no active sitter cookie. GET /api/calendar (My Day) allows any signed-in Access user when Settings → People → Who sees what enables My Day for their audience; owners in owner device mode load the feed directly, and owners in guest/sitter device mode need their owner PIN once per session (same as other owner-only apps). Virtual Button controls require owner device mode — sitters cannot trigger Alexa routines even with a valid Access session.
The Pages API proxy forwards the browser Cookie header and returns Worker Set-Cookie headers so device sessions work same-origin.
Sitter handover (before leaving)
- Confirm the tablet is authenticated through Cloudflare Access.
- In Settings, choose Enable House Sitter Mode and confirm.
- Refresh the browser — the dashboard should remain in House Sitter Mode.
- Confirm House Controls work.
- Confirm owner-only apps (Guide Editor, Controls, …) are absent unless enabled for that audience. My Day appears only when you turned it on for sitters/guests in Settings → People.
Return home
- Use the hidden owner gesture.
- Enter the owner PIN (clears the sitter cookie).
- Confirm Owner Mode loads.
- Reauthenticate through Cloudflare Access if its session has expired.
Required Worker secrets
OWNER_PIN— compared server-side only (never in frontend bundle)OWNER_SESSION_SECRET— device session signingOWNER_EMAILS— comma-separated owner emails for Access role mapping
My Day (personal calendar)
My Day is a read-only personal agenda on the hub — not a full calendar replacement. It shows today, tomorrow, and the next six days from the owner's published ICS feed (Apple Public Calendar link or any HTTPS ICS URL saved in hub secrets).
My Day app + Home card (when enabled for the active audience)
│
▼
GET /api/calendar (valid Access session + device session; audience gate)
│
├── Owners in owner device mode — load without extra PIN when allowed
├── Owners in guest/sitter device mode — owner PIN once per session (#LH-30)
├── Family / sitter / guest — only when My Day is ticked in Settings → People
├── 5-minute normalized cache (`worker/src/calendar/calendarCache.js`)
├── Provider abstraction (`CalendarProvider` / `AppleIcsProvider`)
├── ICS parse + recurrence expansion (`ical.js`, Apple VTIMEZONE from feed)
└── Europe/London date grouping and data minimisation
│
▼
ICS URL (Worker secret `APPLE_CALENDAR_ICS_URL` and/or D1 `calendar_ics_url`)- Default visibility: My Day is off for family, sitters, and guests until enabled per audience in Settings → People → Who sees what.
- House Sitter Mode: My Day is hidden from the launcher when the app is not allowed for the active audience; no calendar HTTP requests are made when the app is not shown.
- Authorization:
/api/calendaruses device session + audience settings (worker/src/routes/calendar.js); it is not limited to Cloudflare Access “owner” role when My Day is enabled for sitters or guests on a stay. - Stale fallback: If Apple is unreachable, the Worker serves the last cached normalized payload with
stale: true. - Read-only: No create/edit/delete; no month grid.
Deployment: my-day-deployment.md.
Appliance Manuals
Owner-uploaded PDF user guides for appliances. PDFs live in a private R2 bucket (APPLIANCE_GUIDES); metadata lives in D1 (APPLIANCE_MANUALS_DB). House sitters browse published manuals from House Guide → Appliance Manuals; owners manage guides from the Appliance Manuals app (Owner Mode only).
See appliance-manuals.md for bindings, migrations, authorization, and Preview/Production setup.
Cloudflare Worker API
Virtual Buttons and private house values are served through a Cloudflare Worker — see cloudflare-worker.md. The PWA uses VITE_API_BASE_URL; the Virtual Buttons access code never ships to the browser.
Adding a new application
- Create
src/apps/MyApp/MyAppApp.jsandindex.jswithregisterApp(). - Add the app id to
APP_DISPLAY_ORDERinsrc/services/appRegistry.js. - Optionally add a widget under
src/widgets/if the app composes reusable UI.
No changes to app.js are required when using the glob barrel.
Adding a new widget
- Create
src/widgets/MyWidget/withindex.jsthat callsregisterWidget(). - Mount it from the app that owns the user task.
Routing
- Default route: Home (no hash)
- Apps:
#/{app-id}(e.g.#/house-guide) navigate()updates history without a full page reload; the shell swaps the viewport content with a short CSS transition.