Family Hub

Project summary · Last updated May 2026 · Current build v6.9 · All modules stable · Direction D visual overhaul complete

v6.9
Current build
5,756
Lines of code
345
Functions
42
Distinct screens
4
Modules live
14
Days to build
~101
Est. hours invested
£0
Monthly infra cost
20
Sheets tabs (DB)
4
Security layers
0
npm dependencies
4
User roles
Overview
Architecture
Security
Modules
UI & UX
Testing & Quality
Environments
Limitations
Glossary
Build history
Roadmap
Backlog & notes
What is Family HubLive

A feature-complete family management web app for chores, trades, tokens and rewards. Built entirely in vanilla HTML, CSS and JavaScript — no framework, no build step, no npm dependencies. Google Sheets serves as the database via a Cloudflare Worker proxy. The app is deployed on Cloudflare Pages behind Zero Trust access control, with a separate public-facing documentation site.

Designed initially for a single family as a cost-efficient proof of concept, with an architecture that can evolve to serve multiple families. Built solo over approximately 14 days (est. ~101 hours) with AI assistance throughout design, engineering and testing.

APP
app.nyefome.uk
Cloudflare Pages · Zero Trust protected
GUIDE
guide.nyefome.uk
Cloudflare Pages · publicly accessible
API
Cloudflare Worker
Proxy between app and Google Sheets · session auth
DATABASE
Google Sheets · 20 tabs
All data · read/write via Worker · never client-side
SOURCE
Private GitHub repo
Single HTML file · no build pipeline · manual deploy
PHASE
Trial launch active
One full cycle · one family · metrics collection ongoing
Module status
👤
Module 1 — Identity & Family
Profiles · PIN auth · 4 roles · families · join flow · PIN resets · Super Admin · archive
Stable
✓
Module 2 — Chore Tracker
Zones · generation · daily bar · W1–W5 pills · section counts · weekly summary bar · reports
Stable
⇄
Module 3 — Trades & Tokens
Swap · offload · token economy · 4-condition guard · parent approval · gifting · ledger
Stable
🏆
Module 4 — Rewards
5-trigger scheme engine · catalog · task bonuses · streaks · monthly completion · templates
Stable
?
Module 5 — TBD
Not yet scoped · possible: scheduling layer · goal tracking · richer analytics
Planned
Why this architecture is notable
Zero dependencies, zero build step
No React, no Vue, no webpack, no npm. A single HTML file with embedded CSS and JS. Ships by dragging a file into Cloudflare Pages. Any developer can read and modify the entire codebase in a browser.
£0/month infrastructure cost
Cloudflare free tier covers Pages, Workers and Zero Trust for small scale. Google Sheets free tier covers the database. The app costs nothing to run at family scale.
Built in 14 days including security hardening
4 full modules + 3-tier security (Worker proxy, server-side PIN auth, security headers) + dark mode + documentation site. Estimated ~101 hours of focused development.
Designed to evolve
Started as the simplest cost-efficient solution for one family. Architecture separates concerns cleanly — Google Sheets can be replaced with Cloudflare D1 without touching the app HTML. Worker handles all data operations already.
Private key never touches the client
v6.0 migration moved all Google Sheets API calls behind a Cloudflare Worker. No credentials are accessible via browser DevTools. Session tokens are scoped by role and expire automatically.
System architecture

Four distinct layers, each with a clear responsibility. The app HTML never communicates with Google Sheets directly — all data access is mediated by the Cloudflare Worker.

CLIENT
Browser
HTML/CSS/JS
HTTPS + Zero Trust
EDGE
Cloudflare
Pages · Zero Trust · Worker
Service account
DATA
Google Sheets
20 tabs · API v4
Request flow — authenticated data read
1
User opens app.nyefome.uk
Request intercepted by Cloudflare Zero Trust. Unauthenticated users are redirected to the Cloudflare login page before the app HTML is ever served.
2
App loads, user enters username + PIN
The app POSTs {username, pin} to the Cloudflare Worker at the API endpoint. No PIN hash or raw data is in the HTML.
3
Worker verifies PIN server-side
Worker fetches the profile from Google Sheets, compares the submitted PIN hash, checks rate limits, and on success issues a signed session token scoped to the user's role.
4
Session token returned to app
All subsequent API calls carry the session token as a Bearer header. The Worker validates the token before executing any Sheets read or write.
5
Data returned, dashboard rendered
Worker proxies the Sheets API response back to the client. The private service account key never leaves the Worker environment.
Technology stack
HTML · CSS · Vanilla JavaScript
Entire frontend in a single file. No framework, no transpiler, no bundler. All state managed in JS module-level variables. Screen navigation via show/hide rather than routing.
Cloudflare Pages
Hosts the app HTML. Deploy by uploading a single file. CDN-distributed globally. Free tier. Custom domain via Cloudflare DNS with auto-provisioned SSL.
Cloudflare Workers
Serverless edge function acting as API proxy. Holds the Google service account private key. Handles PIN verification, session token issuance, rate limiting and all Sheets API calls. CORS locked to nyefome.uk origins.
Cloudflare Zero Trust
Access control layer in front of app.nyefome.uk. Scoped precisely to that subdomain — guide.nyefome.uk is explicitly public. Provides a first line of defence before any app code executes.
Google Sheets API v4
20-tab spreadsheet as relational-style database. Batch reads on login load all required data into memory. All writes go through the Worker. Sheets chosen for cost (free) and zero setup overhead for initial scale.
Google Cloud — Service Account
Authenticates the Worker to the Sheets API. Private key stored as Cloudflare Worker secret, never in source code or client HTML.
GitHub — Private repository
Source control. Single HTML file per version. No CI/CD pipeline — manual upload to Cloudflare Pages on each release.
Database — Google Sheets schema (20 tabs)
Profiles
id · name · username · pin (hashed) · colour · isSuperAdmin · isTemp · createdAt
Families
id · name · joinCode · status (active|archived) · createdAt
FamilyProfiles (memberships)
id · familyId · profileId · role · joinedAt
JoinRequests
id · familyId · profileId · status · createdAt
PinResets
id · familyId · profileId · tempPin · status · createdAt
GlobalChores · FamilyChores · Zones · ZoneChores · ZoneAssignments
Chore library (global + per-family) · zone definitions · zone-chore mappings · monthly child assignments
ChoreLog (20 columns A:T)
id · familyId · profileId · choreId · zoneId · scheduledDate · weekStart · status · confirmedBy · confirmedAt · freq · origin · tradeId · adHocRewardId (col T)
Trades · TokenLedger · Notifications
Trade records (model/stage/tokens) · full token event log · in-app notification queue
RewardSchemes · RewardCatalog · EarnedRewards
Scheme config JSON · reusable reward entries · triggered reward records per child per cycle
WeeklySummaries · MonthStatus
Generated weekly completion snapshots · monthly cycle open/close state per family
Deployment process
1
Build — edit family-hub-vX_Y.html
Changes made in a single HTML file. Bumped version string. Verified against test environment.
2
Test — test.nyefome.uk
Cloudflare Pages · test.nyefome.uk · Separate Sheets database. All four role views tested manually before promotion.
3
Deploy — Cloudflare Pages upload
File dragged into Cloudflare Pages dashboard → Deploy. Live in seconds. Zero downtime. Rollback by redeploying previous version.
Security overview

The app's security model evolved significantly during development. The initial version had the Google service account private key embedded in the client HTML — readable by any authenticated user via browser DevTools. A three-tier hardening plan was identified and fully implemented in v6.0–v6.3, resulting in a defence-in-depth architecture where no sensitive credential is ever accessible client-side.

The Zero Trust layer was already in place and provides strong perimeter protection. The three tiers add security within that perimeter.

Defence layersAll active
ZT
Cloudflare Zero Trust — Perimeter
No unauthenticated browser request ever reaches the app HTML. Cloudflare Access intercepts every request to app.nyefome.uk and enforces identity verification before serving any content. This layer is independent of all app-level auth.
Scoped to app.nyefome.uk exactly — guide.nyefome.uk is intentionally public
Blocks unauthenticated users before app code executes
Provides audit trail of access attempts via Cloudflare dashboard
Active
T1
Tier 1 — Cloudflare Worker Proxy (v6.0)
The most significant architectural change. The Google service account private key was removed from the client HTML entirely and moved into a Cloudflare Worker secret. All Google Sheets API operations are now proxied through the Worker — the browser never communicates with sheets.googleapis.com directly.
Private key stored as Cloudflare Worker secret — not in source code
CORS locked to nyefome.uk origins only
All read/write operations server-side
Migrated from static (direct Sheets API) to dynamic (Worker proxy) simultaneously
v6.0
T2
Tier 2 — Server-side PIN Auth + Rate Limiting
PIN verification moved from the browser to the Worker. Previously the app fetched raw PIN hashes from Sheets to the client for comparison — any authenticated user could read all hashes. Now credentials are submitted to the Worker, which performs verification server-side and returns a role-scoped session token.
Username + PIN submitted to Worker — never compared client-side
Worker issues signed session token on success, scoped to user role
Session tokens carried as Bearer headers on all subsequent API calls
Session expiry handled — expired tokens trigger graceful re-login
Rate limiting on login attempts — lockout after repeated failures
Raw PIN hashes never leave the server environment
v6.x
T3
Tier 3 — HTTP Security Headers
Security headers applied via Cloudflare Transform Rules — applied at the edge before any response reaches the browser. Prevents a range of common web attacks including clickjacking, content injection and MIME sniffing.
Content-Security-Policy — restricts resource origins
X-Frame-Options: DENY — prevents clickjacking via iframe embedding
X-Content-Type-Options: nosniff — prevents MIME type sniffing
Referrer-Policy: no-referrer — prevents URL leakage in referrer headers
v6.x
Super Admin data isolationPrivacy feature

The Super Admin role is scoped to platform administration only. A Super Admin can see that a family exists, its name and member count — but cannot access any family content: no chores, no trades, no rewards, no member personal data. This is a deliberate privacy boundary enforced at the application level.

✓
SA dashboard shows family metadata only
Name, member count, pending request count. No chore data, no token data, no reward data is loaded for SA sessions.
✓
SA cannot navigate into family modules
Chore Tracker, Trades, Rewards and Reporting modules are not accessible from the SA dashboard. SA actions are limited to rename, archive/unarchive and global chore library management.
✓
SA PIN reset scope limited to Admin profiles only
SA only sees PIN reset requests from Admin-role profiles across families, not from Parent or Child profiles. Family-level PIN resets are handled by that family's Admin.
✓
Role-scoped session tokens
Session tokens carry role information. The Worker rejects requests for data scopes that don't match the session role — SA tokens cannot fetch ChoreLog or reward data even if called directly.
In-app authorisation model
Role-based screen routing
On login, routeToDashboard() directs each user to their role-specific screen. Admin, Parent and Child dashboards are distinct. No role can navigate to another role's screens via the UI.
Child data isolation
Children see only their own chores, trades, tokens and rewards. The ChoreLog, TokenLedger and EarnedRewards queries are filtered server-side by profileId. No child can access a sibling's data.
Role change guards
Admin cannot change their own role. Last Admin in a family cannot be demoted. Max 2 Admins enforced. All role changes are validated before write.
Trade guards (4-condition check)
Before any trade is allowed: initiator token check · recipient token check (swaps) · no active trade on same chore · chore not locked awaiting confirmation.
PIN security
PINs are hashed before storage. Temp PINs (for resets) are single-use and expire. Child sets permanent PIN on first login with temp PIN. PIN changes require current PIN confirmation.
Deferred — Cloudflare D1 migrationFuture

Google Sheets is functional at current scale but is not a production-grade database for multi-family use. The planned D1 migration replaces Sheets with Cloudflare's serverless SQLite, keeping all data within the Cloudflare ecosystem. Because the Worker already mediates all data access, this migration requires no changes to the app HTML — only the Worker's data layer changes.

Module 1 — Identity & FamilyStable
✓
Profile creation — name, username, avatar colour, 4-digit PIN
✓
PIN login — hashed storage, on-screen keypad, no keyboard input
✓
4 roles — Super Admin · Admin · Parent · Child — with distinct dashboards
✓
Family creation — unique join code, Admin auto-assigned to creator
✓
Join flow — code entry → pending request → Admin approve/reject
✓
Multi-family support — one profile can belong to multiple families
✓
Role change — Admin changes other members' roles with dual-Admin guard and last-Admin protection
✓
PIN reset flow — child requests → Admin generates temp PIN → child sets new PIN on login
✓
Admin proactive PIN reset — Admin generates temp PIN for any member without a request
✓
Settings screen — change display name, change PIN (requires current PIN)
✓
Super Admin dashboard — all families, SA profiles, global chore library, SA-scoped reset requests
✓
Archive/unarchive family — name confirmation gate · all members notified · archived screen on next login
✓
Live refresh button — all four dashboards re-fetch join requests, resets and chore log on demand
Module 2 — Chore TrackerStable
✓
Zone management — create, name, assign chores, assign to children monthly
✓
Chore frequencies — daily · weekly · bi-weekly · monthly — auto-generated on month open
✓
Daily chore 7-day progress bar — Green (confirmed) · Amber (today) · Red (lapsed) · Grey (future)
✓
Weekly/bi-weekly W1–W5 pill consolidation — one row per chore across all weeks
✓
Weekly summary info bar — confirmed/pending/lapsed counts + "X chores left for a perfect week" message
✓
Section count badges — 📅 Daily (N) · 🗓 Weekly (N) · Bi-weekly (N) · Monthly (N) · Ad-hoc (N)
✓
Week-specific mark-done button — "W2 done" label removes ambiguity for weekly chores
✓
Chore origin badges — REG · AD-HOC · SWAP · OFFLOAD on every chore row
✓
Mark done → parent confirmation → 48h auto-confirm → lapse detection
✓
Confirm & Query stay on chore tracker — no navigation away from the overview screen
✓
Ad-hoc task assignment — parent creates for child with optional reward · child self-assigns available tasks
✓
Cross-zone chore guard — chores assigned to Zone A appear greyed in Zone B picker with zone label
✓
Month open/close — zone rotation auto-runs on close · chore instances generated on open
✓
Family overview — per-child completion % · progress bar · frequency breakdown tiles
✓
Weekly summaries — generated each cycle · historical weekly average completion rates
✓
Reporting charts — stat cards · bar chart · line chart · period-based completion rates per child
Module 3 — Trades & TokensStable
✓
Swap trades — both children pay 1 token · multi-step initiation flow with back/cancel at each step
✓
Offload trades — initiator pays 1 token · recipient accepts or declines for free
✓
4-condition trade guard — token check · recipient token check · no active trade · chore not locked
✓
Parent approval queue — approve/reject with full trade detail · both children notified of outcome
✓
Token economy — 2/month auto-issued · carry-forward cap 4 · bonus uncapped · quarterly reset
✓
Spend priority — monthly tokens first · carried tokens second · bonus tokens last
✓
Gift tokens — parent/admin gifts bonus tokens · added immediately to child balance
✓
Token ledger — every event logged with type · amount · source · description · timestamp
✓
Task bonus forfeit warning — amber modal names reward forfeited if trade proceeds
✓
Dashboard banners — Purple (action required) · Teal (update) · Amber (parent/admin alert)
Module 4 — RewardsStable · most complex module
✓
Reward catalog — reusable reward library (type · label · value) · referenced across schemes and ad-hoc tasks
✓
Reward scheme — one active per family per month · 5 trigger types · per-child configuration
✓
Trigger 1 — Perfect week: child completes every chore in a week with no lapses
✓
Trigger 2 — Threshold %: child hits a set weekly completion % (e.g. 80%) · rewards effort
✓
Trigger 3 — Streak milestones: consecutive qualifying weeks · configurable target (2 weeks, 4 weeks etc.)
✓
Trigger 4 — Task bonus: reward attached to a specific chore · fires automatically on confirmation · no parent action
✓
Trigger 5 — Monthly completion: overall % for the month · evaluated at month close
✓
Evaluation engine — runs at week boundary and month close · deduplicates by triggerType + weekStart
✓
Scheme form — child selector tiles · frequency grouping · task bonus store persists across child switching
✓
72-hour scheme setup window — from zone rotation (or family.createdAt for new families)
✓
Scheme templates — save · browse · rename · delete (soft) · apply · blocked when active scheme exists
✓
Ad-hoc rewards — parent creates one-off tasks with optional reward · child self-assigns triggers parent notification
✓
Children this cycle — tappable cards → per-child detail screen with full trigger/bonus breakdown
✓
Issue rewards — Mark issued workflow · child can see earned-but-not-issued rewards on their screen
Design system — Direction D (v6.9)Updated

v6.9 delivered the Direction D visual overhaul — a full CSS rewrite layered over the unchanged HTML and JS. The visual language shifted from clean white/neutral to a warm "Soft Notebook" greige palette with handwritten headings, 3D pill buttons and shadow-based depth. All 42 screens updated with no logic changes.

BODY FONT
DM Sans
Google Fonts · replaces Plus Jakarta Sans
HEADING FONT
Caveat
Handwriting · h1/h2 across all screens · 40–30px
LABEL FONT
JetBrains Mono
Monospace · section titles · badges · uppercase
PALETTE
Greige — 5 semantic tints
Peach · Mint · Lemon · Lilac · Sky — each with bg/dp variants
BUTTONS
3D pill — border-radius: 999px
box-shadow depth (4px drop + 1px inset highlight) · presses on :active
CARDS
Shadow-based · paper bg
No borders · warm box-shadow · --paper: #F0ECE3
NAV BARS
Dashed borders
topnav + screennav · 1px dashed rgba(42,39,34,0.18)
MASCOT
Marshmallow SVG
Inline-rendered · login · first-run · PIN · forgot screens
DARK MODE
Re-mapped for greige
Dark values updated · --bg #1F1D18 · --paper #34312B · peach primary retained
SCREENS
42 distinct screens
Show/hide navigation · no page reloads · all HTML/JS untouched
Direction D visual translation — v6.9Complete
🎨
CSS-only overhaul — all HTML and JS untouched
A second <style id="dirD-overrides"> block layered after the base CSS. Every existing id, onclick and renderX() function kept working. The app looks brand-new; the engine is identical.
🖊
Caveat handwriting headings
All h1 and h2 elements now render in Caveat cursive at 40px/30px. Creates an immediate "soft notebook" personality — family names, screen titles and module headings all feel handwritten.
⬤
3D pill buttons with press depth
border-radius: 999px on all buttons. Primary (peach) carries a 4px bottom shadow + 1px inset highlight. Active state translates 2px down and compresses the shadow, giving genuine tactile press feedback.
🃏
Shadow-based card depth — no flat borders
Cards replaced with --sh-tile and --sh-key shadow systems: bottom-edge shadow + inset top highlight. Cards appear to sit slightly above the page surface. Lift effect on hover for interactive tiles.
🧸
Marshmallow SVG mascot
An inline SVG character resolves dynamically from [data-mascot] attributes. Five colour variants (peach, mint, lemon, lilac, sky) and two decoration modes (sparkle, cloud). Appears on login, first-run, PIN change, forgot-PIN and SA recovery screens. MutationObserver handles dynamically injected screens.
✏️
JetBrains Mono labels and monospace badge system
Section labels, form field labels and role badges use JetBrains Mono at 9–10px with 0.14em letter-spacing and uppercase. Creates a clean "printed annotation" contrast against the Caveat headings and DM Sans body text.
Dark mode — v6.7Live
🌙
Toggle in Settings — all roles
A CSS toggle switch appears in the Settings screen for every role (Super Admin, Admin, Parent, Child). One tap switches theme instantly — no page reload.
💾
localStorage persistence
Theme preference stored as fh_theme in localStorage. Persists across sessions on the same device. Reads and applies on page load before render to prevent flash.
⚙️
System preference detection
prefers-color-scheme media query checked on first load. If no saved preference exists, the app automatically matches the device OS setting.
🎨
45 dark-mode CSS overrides
Applied via [data-theme="dark"] attribute on documentElement. Covers all badge variants, action buttons, inputs, select dropdowns, banners, trade cards and reward elements. Components using CSS variables adapt automatically.
🔧
isDark() helper
JS helper isDark() used where inline styles (e.g. reward banners) need programmatic colour selection. Keeps dark-mode logic consistent across both CSS and JS-rendered elements.
UX design principles
👁
Role-contextual UI
Every role sees only what's relevant to them. Child dashboards are clean and focused. Admin dashboards surface management actions. No role is overwhelmed with irrelevant options.
📱
Mobile-first layout
Designed for phone use on a shared family device. Large tap targets, on-screen keypad, card-based layout, scrollable lists. Tested on phone and tablet.
🎨
Colour-coded identity
Every family member has a colour chosen at profile creation. That colour appears on their avatar throughout — dashboards, chore assignments, trade requests, zone tiles. Instant visual recognition.
🔔
Action-required banners
Coloured banners surface pending actions at the top of dashboards. Purple = trade approval needed. Amber = scheme or cycle action needed. Green = update available. Tapping goes directly to the relevant screen.
⚠️
Contextual warnings before irreversible actions
Trade forfeit warning names the reward lost before proceeding. Archive family requires typing the family name. Role changes and month close are clearly staged. No destructive action without confirmation.
↺
Inline refresh without navigation
↻ Refresh button on all dashboards re-fetches live data without navigating away. Confirm/query actions on the chore tracker stay on the same screen. Reduces disorientation from unnecessary screen transitions.
Screen inventory — 42 screens
Authentication & onboarding
s-logins-pins-forgots-first-runs-create-profiles-create-familys-join-familys-family-pickers-family-optionss-family-codes-pendings-archived-family
Dashboards
s-superadmins-admins-parents-child
Identity management
s-manage-familys-manage-memberss-settingss-change-pins-familiess-sa-choress-sa-recovery
Chore tracker
s-zone-setups-zone-choress-zone-assign-childrens-add-family-chores-chore-pickers-parent-overviews-child-choress-child-details-assign-adhocs-reporting
Trades & tokens
s-mod3s-mod3-parents-initiate-trade
Rewards
s-rewardss-reward-schemes-reward-catalogs-scheme-templatess-child-rewards-detail
System
s-loadings-error
Testing philosophy

Testing is primarily manual and role-based, supported by a dedicated test environment at test.nyefome.uk backed by a separate Sheets database. Every build is validated across all four roles before promotion to production. The two-environment gate is the primary quality control mechanism.

Given the single-file, no-framework architecture, there is no unit test runner or CI pipeline. Test coverage is behavioural — each feature is validated end-to-end through the UI as a real user would use it. This approach was chosen for speed of iteration during the initial build phase.

Test environmenttest.nyefome.uk
✓
Separate Sheets database
Test environment uses an entirely separate Google Sheets file with its own test data. Changes to test data never affect production families.
✓
Test environment banner
A persistent amber banner across every screen in test.nyefome.uk confirms you are not on the live app. Prevents accidental confusion between environments.
✓
ENV-aware configuration
The app auto-detects environment from the URL and switches SHEET_ID and API endpoint accordingly. No manual flag needed when switching between environments.
✓
Promotion gate
Every build deploys to test.nyefome.uk first. Only after passing full role-based validation is the file uploaded to app.nyefome.uk. No version has ever been promoted with a known failing test.
Pre-release validation checklist
Authentication
✓
Login — correct PIN grants access, wrong PIN rejected
✓
Role routing — SA · Admin · Parent · Child each land on the correct dashboard
✓
PIN reset flow — request → temp PIN → forced new PIN on login
✓
Session expiry — expired session triggers graceful re-login, not an error
Module 1 — Identity
✓
Profile creation and family join flow end-to-end
✓
Join request approval and rejection — both paths
✓
Role change guards — cannot change own role, last-Admin protection, max-2 Admin
✓
Archive family — name confirmation, archived screen, unarchive
Module 2 — Chore Tracker
✓
Month open/close — chore generation, zone rotation, new cycle visible to children
✓
Mark done → pending → confirm/query → 48h auto-confirm
✓
Daily bar colours — confirmed/today/lapsed/future correct for date
✓
Weekly pills — W1–W5 status, biweekly strikethrough, "W2 done" button label
✓
Weekly summary bar — counts correct, perfect week message fires
✓
Cross-zone guard — chore assigned to Zone A greyed in Zone B picker
Module 3 — Trades & Tokens
✓
Swap flow — initiate, recipient accepts, parent approves, chores exchanged
✓
Offload flow — initiate, recipient accepts/declines, parent approves
✓
4-condition guard — all four blocked states tested individually
✓
Token economy — spend priority order, carry-forward cap, quarterly reset
✓
Task bonus forfeit warning — amber modal appears when bonus chore is traded
Module 4 — Rewards
✓
All 5 triggers fire correctly — perfect week, threshold, streak, task bonus, monthly
✓
72h scheme window — open for new families, closes after window for existing
✓
Template save, apply, rename, delete
✓
Reward evaluation runs at month close — earned rewards appear correctly
✓
Mark issued workflow — clears from pending, child sees issued state
Security
✓
Rate limiting — repeated wrong PINs trigger lockout
✓
SA data isolation — SA cannot navigate to chore/trade/reward data
✓
Child data isolation — Child A cannot see Child B data
✓
Security headers present — verified via browser DevTools and headers check
✓
Dark mode — toggle, persistence, system preference on fresh load
Automated testing
Some automated tests in place
Automated coverage exists for selected flows alongside the primary manual validation approach. Scope to be expanded as the project matures.
No CI/CD pipeline — manual deploy
No automated test runner fires on commit. Test discipline is enforced by the two-environment promotion gate rather than automated pre-commit checks. Adding CI is a future consideration as the codebase stabilises.
Trial period — metrics collection starting
First real-usage data will come from the trial launch. Performance, usage patterns and edge cases encountered in production will inform the next testing priorities.
Environment overview

Three distinct environments serve different purposes. All three share the same codebase but point to different Sheets databases and API endpoints. Promotion always flows in one direction: test → production. The guide is environment-independent — it covers the app generally and is not tied to a specific build.

test.nyefome.uk Test
Purpose
All new builds deployed here first. Full feature validation across all four roles before any code reaches production. Safe to experiment — test data can be reset at any time.
Access
Cloudflare Pages. No Zero Trust restriction — accessible to anyone with the URL for ease of testing. Amber "TEST ENVIRONMENT — data here is not live" banner on every screen.
Database
Separate Google Sheets file from production. Test families, test profiles and test data. No crossover with live data.
API endpoint
ENV-aware — app auto-detects test.nyefome.uk and routes API calls to the test Worker endpoint and test SHEET_ID.
Deploy method
Manual file upload to the test Cloudflare Pages project. Immediate — no build step required.
app.nyefome.uk Production
Purpose
Live application serving the family. Only promoted builds reach this environment — no direct editing or experimentation.
Access
Cloudflare Pages behind Cloudflare Zero Trust. Unauthenticated requests are intercepted before the app HTML is served. Zero Trust scoped to app.nyefome.uk precisely — does not apply to other subdomains.
Database
Live Google Sheets — the real family database. All active profiles, chore logs, trades, tokens and rewards.
API endpoint
Production Cloudflare Worker. Holds the live service account private key as a Worker secret. CORS restricted to nyefome.uk origins.
Deploy method
Manual file upload to the production Cloudflare Pages project after passing test validation. Rollback: re-upload the previous version file.
Security headers
CSP · X-Frame-Options: DENY · X-Content-Type-Options: nosniff · Referrer-Policy: no-referrer — applied via Cloudflare Transform Rules.
guide.nyefome.uk Documentation
Purpose
Public-facing user guide. Shareable with new family members before they join — no login required. Covers all modules, roles, step-by-step flows and troubleshooting.
Access
Cloudflare Pages — intentionally public. Zero Trust explicitly does not apply to this subdomain. Anyone with the link can access it.
Content
Single HTML file. Visual overview (CSS phone-frame mockups) + 7-tab detailed reference guide. Anonymised — uses "Taylor family" placeholder data, not real family names. Last updated May 2026.
Update process
Download updated index.html from Claude → upload to the family-hub-guide Cloudflare Pages project → deploy. Live in seconds, same URL, no DNS changes.
Future
Consider connecting to a Git branch for auto-deploy when guide updates become more frequent. Currently manual upload is sufficient given infrequent changes.
Promotion flow
1
Edit family-hub-vX_Y.html
Bump version string. Make changes. Save.
2
Deploy to test.nyefome.uk
Upload to test Cloudflare Pages project. Verify amber test banner is showing.
3
Validate all affected flows
Test each changed feature across all relevant roles. Run through the pre-release checklist for impacted modules.
4
Promote to app.nyefome.uk
Upload same file to production Cloudflare Pages project. Live within seconds. No downtime.
5
Verify on production
Quick smoke test on app.nyefome.uk — login, role routing, key feature check. Confirm no test banner is showing.
6
Archive the version file
Keep the previous version file available for instant rollback if needed.
Engineering context

These limitations are the result of deliberate early-stage trade-offs — choosing speed of delivery and zero cost over architectural perfection. Each one has a known resolution path. The app works correctly within these constraints at current scale, and the architecture is designed to evolve without requiring a rewrite.

Database — Google SheetsD1 migration planned
!
No true concurrent write safety
Google Sheets has no row-level locking. If two users write to the same range simultaneously, one write may overwrite the other. At single-family scale with low concurrent usage this is unlikely — at multi-family scale it becomes a real risk. Resolved by D1 migration (SQLite transactions).
!
API rate limits (Google Sheets)
Google Sheets API v4 has a quota of 300 read requests per minute per project. A batch login read currently consumes 15 requests. At ~20 concurrent logins this approaches the limit. Resolved by D1 migration (no external API quota).
!
No relational queries — data fetched in bulk
Sheets has no JOIN or filtered query capability. All relevant tabs are fetched into memory on login and filtered client-side. As data volumes grow, login time increases. Resolved by D1 with proper SQL queries.
~
Row count performance
ChoreLog grows by ~(chores per child × children × days) per month. At single-family scale this is manageable. A 3-child family running for 12 months accumulates ~10,000–15,000 rows. Google Sheets handles this fine but Sheets API read time increases with sheet size.
Architecture — single HTML file
!
No code splitting — full file loaded on every visit
At 419KB (v6.7) the entire app — CSS, JS and HTML for all 42 screens — loads upfront. For most connections this is fast, but it is not optimal. Resolved by migrating to a framework with code splitting if/when scale demands it.
~
No automated CI/CD
Deployment is a manual file upload. There is no automated test runner, no linting step and no pre-commit validation. Human discipline and the two-environment gate substitute for CI. Acceptable at current velocity — would need to change for a team build.
~
All state in module-level JS variables
App state (allProfiles, allChoreLog, allTrades etc.) lives in JS variables. A full page reload resets all state and re-fetches from Sheets. Sessions do not persist across browser closes. This is intentional for security (no sensitive data in localStorage) but means no background sync.
~
No offline capability
The app requires an active internet connection. No service worker, no local caching of data. Acceptable for home use on a shared device.
User experience constraints
~
No push notifications
The app is browser-only with no service worker. Notifications (trade requests, chore confirmations, reward alerts) are only visible when the app is open. Children won't be alerted on their phone when a parent confirms a chore. A future consideration alongside any PWA work.
~
No persistent login across devices
Sessions are in-memory and scoped to the current browser tab. Closing the browser or switching device requires re-login. Deliberate — keeps sensitive family data out of persistent storage — but less convenient for frequent users on multiple devices.
~
No formal accessibility audit
The app uses semantic HTML elements, sufficient colour contrast in light mode and large tap targets. Dark mode improves contrast in low-light conditions. No formal screen reader or WCAG audit has been conducted. A future consideration before any public release.
~
UI polish deferred
The current UI was AI-generated and iterated during development. It is functional and consistent but not yet production-polished. A dedicated design sprint is planned before wider rollout.
Resolution roadmap
D1 migration resolves all database constraints
Concurrency, rate limits, query efficiency and bulk-fetch performance all resolved in a single migration. Worker already mediates all data — only the data layer changes, not the app HTML.
UI polish sprint — near term
Planned before extending to additional families. All 42 screens reviewed, spacing and typography tightened, dark mode refined.
Push notifications, PWA, accessibility — longer term
These would require meaningful architectural additions. Not needed for the current single-family trial. Reconsidered when scaling to multiple families.
Key terms

Terms used throughout the app, this document and the user guide.

Roles
Super Admin (SA)
Platform-level administrator. Manages all families, SA accounts and the global chore library. Cannot access any family content. App owner only.
Admin
Family operator. Full control within their family — cycles, zones, chores, members, rewards, trades. Maximum 2 per family.
Parent
Family participant with elevated permissions. Confirms chores, approves trades, gifts tokens, manages rewards. Cannot change member roles.
Child
Primary daily user. Marks chores done, proposes trades, views their own rewards. Cannot see siblings' data.
Chore tracker
Zone
A named grouping of chores (e.g. "Kitchen", "Garden"). Assigned to one child per month. Zones rotate between children at month close.
Cycle / Month
The active monthly period. Opened by an Admin (generates chore instances) and closed by an Admin (triggers zone rotation and reward evaluation). Not always calendar-aligned.
Rotation
The automatic reassignment of zones to children when a month is closed. Each child moves to the next zone in the rotation order.
Chore instance
A specific occurrence of a chore on a specific date (or week), generated when the month is opened. Distinct from the chore definition in the library.
Frequency
How often a chore recurs within a cycle. Values: daily · weekly · bi-weekly · monthly.
Origin badge
Label on every chore row showing how it arrived: REG (regular) · AD-HOC (one-off assigned) · SWAP (received via trade) · OFFLOAD (taken on via trade).
48-hour auto-confirm
If a parent/Admin does not confirm or query a chore marked done within 48 hours, it confirms automatically.
Lapsed
A chore that passed its due date without being marked done. Shown in red. Counts against completion percentage and streak calculations.
Perfect week
A week in which every due chore is confirmed complete with no lapses. Triggers the perfect week reward if configured.
Trades & tokens
Swap
A trade where two children exchange one chore each. Both children pay 1 token. Requires parent approval.
Offload
A trade where one child pays to give a chore to another. Initiator pays 1 token; recipient accepts or declines for free. Requires parent approval.
Monthly token
2 tokens auto-issued to every child at the start of each cycle. Spent first.
Carried token
Unspent monthly tokens that roll over to the next month. Capped at 4 total. Spent second.
Bonus token
Tokens gifted by a parent or Admin. Uncapped. Spent last. Do not count towards the carry-forward cap.
Quarterly reset
Token balances reset to zero each quarter (Jan, Apr, Jul, Oct). Tokens do not carry across quarter boundaries.
Trade guard
One of four checks the app runs before allowing a trade: token balance, recipient token balance (swaps), no active trade on the chore, chore not awaiting confirmation.
Rewards
Reward scheme
A monthly configuration defining what children can earn and how. One active scheme per family per month.
Trigger
A condition that, when met, fires a reward. Five types: perfect week · threshold % · streak milestone · task bonus · monthly completion.
Reward catalog
A reusable library of reward entries (e.g. "£5 cash", "Cinema trip"). Built once, referenced across scheme triggers and ad-hoc tasks.
Task bonus
A reward attached to a specific individual chore. Fires automatically when that chore is confirmed — no parent action required.
Streak
A consecutive run of weeks in which a child meets their qualifying target (perfect or above threshold). Streak milestones fire rewards at configured lengths (e.g. 2 weeks, 4 weeks).
Evaluation engine
The process that runs at week boundary and month close to calculate which triggers have fired and generate earned reward records. Deduplicates by trigger type + week start to prevent double-firing.
Scheme template
A saved copy of a reward scheme that can be loaded in future months. Stores all trigger configurations and task bonuses. Cannot be applied while an active scheme exists.
72-hour setup window
The period after a month opens (or a family is created) during which a new scheme can be created. After the window closes, existing schemes can be edited but a brand new scheme cannot be created until the next rotation.
Issued
A reward that has been given to the child in real life and marked as such by the parent. Clears the reward from the pending list.
Infrastructure & technical
Cloudflare Pages
Static site hosting platform. Serves the app HTML and guide HTML. CDN-distributed, free tier, custom domain support with auto-SSL.
Cloudflare Worker
Serverless edge function. Acts as the API proxy between the app and Google Sheets. Holds the private key, performs PIN verification, issues session tokens and enforces rate limits.
Zero Trust
Cloudflare Access product. Intercepts all requests to app.nyefome.uk and enforces identity verification before serving any content.
Session token
A signed token issued by the Worker on successful PIN verification. Carried as a Bearer header on all subsequent API calls. Scoped to the user's role. Expires after a set period.
ENV-aware
The app detects its environment (test vs production) from the URL on load and automatically selects the correct SHEET_ID, API endpoint and Worker URL. No manual switching required.
Cloudflare D1
Cloudflare's serverless SQLite database product. The planned replacement for Google Sheets as the app's data store. Native to the Cloudflare ecosystem — no external API quota, proper transactions, relational queries.
v6.9
Direction D visual translation + module badge fix. Full "Soft Notebook" visual overhaul: greige token palette (--bg #DCD8D0 · --paper #F0ECE3), Caveat handwriting headings, DM Sans body, JetBrains Mono labels, 3D pill buttons with press-depth shadows, shadow-based cards (no borders), dashed nav borders, Marshmallow SVG mascot on 5 screens, greige dark mode re-map. All implemented as a CSS-only override block — zero HTML or JS changes, all 42 screens updated. Also: module tile badge fix — Chore Tracker tile on Admin and Parent dashboards now correctly shows mint green "View →" pill (matching Trades, Rewards, Reporting) when zone setup is complete. Previously showed grey "Module 2" badge regardless of state. Parent tile badge now has id="par-mod2-badge" for JS targeting; updateMod2Tile() updated accordingly.
Visual
v6.8
Checkpoint build. Staging version ahead of Direction D visual work. No functional changes from v6.7 — version bump only. Base for the v6.9 Direction D overhaul.
Checkpoint
v6.7
Night mode (dark theme). Full dark mode implementation added to all four role dashboards. CSS toggle switch in Settings for every role. localStorage persistence via fh_theme key. System prefers-color-scheme auto-detected on first load. 45 dark-override selectors covering badges, buttons, inputs, banners, trade cards. isDark() helper for JS-rendered inline styles. Version bumped from v6.6.
Feature
v6.6
SA PIN reset scope fix. Super Admin dashboard's reset section now filters to show only Admin-role reset requests across all families. SA no longer sees Child or Parent PIN reset requests — these remain the responsibility of the family's own Admin. Maintains correct privilege separation.
Fix
v6.5
Four fixes. SA dashboard join request notifications: join badge on each family card now navigable — taps into the approve/reject screen for that family. renderManageFamily() now async — fetches fresh JR data from Sheets on every call. ↻ Refresh button added to all four dashboards. isSchemeWindowOpen revised: new families return true unconditionally until first rotation — 72h window only applies after a rotation has occurred.
Fix
v6.4
Chore tracker UX improvements. Weekly progress summary info bar (confirmed/pending/lapsed counts + "X left for a perfect week" message). Section count badges on each frequency group (📅 Daily (N)). Week-specific mark-done button label ("W2 done"). All chore tracker daily/weekly/biweekly display fixes consolidated.
Feature
v6.3
Tier 2 & 3 security complete. Server-side PIN verification in Worker. Role-scoped session tokens issued on successful login. Bearer token carried on all subsequent API calls. Session expiry handling with graceful re-login. Rate limiting on login attempts. HTTP security headers applied via Cloudflare Transform Rules (CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy).
Security
v6.0
Tier 1 security — Cloudflare Worker proxy. Google service account private key removed from client HTML. All Sheets API calls now proxy through Cloudflare Worker. CORS locked to nyefome.uk origins. Static → dynamic migration. apiCall() function replaces direct sheets.googleapis.com calls. getGToken/importPK removed.
Security
v5.9
isSchemeWindowOpen fix. 72h reward scheme setup window now anchored to family.createdAt for new families. Mid-cycle onboarding no longer incorrectly sees a closed window on day 1. (Note: further revised in v6.5 to remove window entirely for new families pre-rotation.)
Fix
v5.8
Bug fixes. New family timing bypass. Join request notification routing fix in multi-family setups.
Fix
v5.7
Cross-zone chore guard. Chores assigned to any zone appear greyed in picker for other zones with zone name shown. Prevents double-assignment. renderPickerList() builds assignedHere and assignedElsewhere sets.
v5.6
Tier 4 completion. Archive family (SA): name-confirmation modal, archived screen, unarchive. Scheme template library: browse, rename, soft-delete, apply (blocked if active scheme exists). SH.FAM and SH.RS shorthand aliases.
Tier 4
v5.5
Module 4 main build. ChoreLog col T (adHocRewardId). Trade forfeit warning. Ad-hoc notifications. evaluateMonthlyCompletion. Scheme form child tiles + frequency grouping + monthly completion + ad-hoc inline editing + scheme tile redesign + save as template. Child-created tasks section. Monthly completion progress bar. Children this cycle → child rewards detail screen.
v5.2
Admin proactive PIN reset. Admin generates temp PIN for any member without a pending request. Frequency chips on overview. Mark Issued redesign. Gift tokens stepper. Parent rewards earned section.
v5.0–5.1
Infrastructure & colour system. URL auto-detection (test vs live). ENV-aware SHEET_ID and SYSTEM_KEY. Test environment banner. Amber colour system locked (#C47F17/#FAEEDA/#633806). Q0 quarterly label fix.
v4.x
Module 4 — Rewards. Scheme form, reward catalog, evaluation engine (4 trigger types), weekly/biweekly pill redesign, chore consolidation (W1–W5), frequency badges. Scheme name field. Task bonus per-child avatar cards. Streak milestone row builder.
M4
v3.x
Module 3 — Trades & Tokens. Swap and offload flows, token economy (monthly/carried/bonus), ledger, notifications, gift tokens, parent approval queue, ME-03 4-condition guard, dashboard banners, chore origin badges. Critical fix in v3.4: afterPinVerified discarding 9 of 15 sheet reads.
M3
v2.x
Module 2 — Chore Tracker. Zones, assignments, auto-generation, weekly summaries, monthly reporting, ad-hoc tasks, daily progress bar.
M2
v1.x
Module 1 — Identity & Family. Profiles, families, PIN auth, 4 roles, join requests, PIN resets, multi-family support.
M1

Current phase — Trial launch

▶
Trial period — one family · one full cycle
All four modules live with Direction D visual overhaul. Performance and usage being measured through the first full monthly cycle. Feedback gathered before extending to additional families.
Active

Near term

1
In-app help link — ? icon in top nav
Small ? icon across all role dashboards linking to guide.nyefome.uk in a new tab. One-line addition per screen. Deferred from v6.5.
Backlog
2
Extend to additional families
Friends and extended family. Architecture already supports multi-family — Super Admin manages all families independently. No code changes required, just new family setup.
Backlog

Medium term

3
Cloudflare D1 database migration
Replace Google Sheets with Cloudflare D1 (serverless SQLite). Worker already mediates all data access — migration requires only the Worker's data layer to change, not the app HTML. Provides proper relational queries, transactions and multi-user safety. Essential for scaling beyond small family groups.
Planned
4
Module 5 — TBD
Not yet scoped. Possible directions: family calendar and scheduling layer, goal tracking beyond chores, richer analytics and trend reporting, push notifications.
Planned

Completed security roadmap

✓
Key rotation — Google service account private key
Done
✓
Tier 1 — Cloudflare Worker proxy (key off client)
v6.0
✓
Tier 2 — Server-side PIN auth + rate limiting + session tokens
v6.x
✓
Tier 3 — HTTP security headers via Cloudflare Transform Rules
v6.x

Completed UI roadmap

✓
UI polish sprint — Direction D visual translation
Greige token palette · Caveat headings · 3D pill buttons · shadow-based cards · Marshmallow mascot · dashed nav borders. CSS-only — all 42 screens, no logic changes.
v6.9
✓
Dark mode — full implementation across all roles
v6.7

Key data model notes

ChoreLog — column T = adHocRewardId
'' = unreviewed · 'none' = reviewed, no reward · [rewardId] = reward assigned
RewardSchemes — status values
'draft' · 'active' · 'template' · 'deleted'. r[5]=status · r[7]=globalRules JSON · r[8]=taskBonuses JSON
Families — status values
'active' · 'archived'. r[3]=status
isSchemeWindowOpen — v6.5 revised
New families (no rotation ever): returns true unconditionally. Existing families: 72h window from last zone rotation date. Change ensures mid-cycle family creation never hits a closed window.
Window._taskBonusSelections
Keyed choreId|profileId. Persists across child switching in scheme form. Cleared on scheme save or cancel.
apiCall(action, range, values)
Central function for all Sheets operations. Attaches Bearer token if sessionToken exists. Handles 401 session expiry with graceful re-login. action: 'read' | 'write' | 'append' | 'delete'
Dark mode — applyTheme(dark)
Sets data-theme on documentElement. Writes to localStorage as 'fh_theme'. Called by toggleNightMode() and on page load. isDark() helper checks current attribute for JS-rendered inline styles.

Open backlog

1. Module 5 — TBD (scoping session pending)
2. Cloudflare D1 migration — replaces Google Sheets · Worker data layer only · no app HTML changes
3. In-app help link — ? icon in top nav linking to guide.nyefome.uk (one line per dashboard)
4. Extend to additional families — friends and extended family · no code changes required

Resolved backlog

✓
UI polish sprint — Direction D visual translation · greige palette · Caveat/DM Sans/JetBrains Mono · 3D pills · shadows · mascot
v6.9
✓
Module tile badge fix — Chore Tracker "View →" green pill aligned with other modules for Admin and Parent
v6.9
✓
Frequency badges on admin/parent family overview
v5.2
✓
Admin proactive PIN reset UI
v5.2
✓
AE-02 Colour scheme review
v5.0/5.1
✓
Q0 quarterly chart label fix
v5.6
✓
All three security tiers
v6.0–6.3
✓
Dark mode
v6.7

Reference files

family-hub-v6_9.html — current build
Direction D visual overhaul · dark mode · all security tiers · all 4 modules · 5,756 lines · 345 functions · 42 screens
index.html (guide.nyefome.uk) — updated v6.9
Combined visual + 9-tab detailed guide · greige phone mockups · Marshmallow mascot · anonymised · publicly hosted on Cloudflare Pages
family-hub-user-guide-v5.9.pdf — PDF reference guide
8-section detailed reference · all modules · roles · flows · troubleshooting · print-ready
family-hub-project-summary_6_9.html — this document