FamilySync setup documentation

From phone account to kitchen wall tablet.

This portal captures the current FamilySync setup system: product intent, onboarding, Supabase schema/RPCs, the Vite phone companion, Android tablet pairing, admin settings, verification commands, and the next implementation decisions.

Read onboarding flow Run verification
Today 7:42 Kitchen display synced
Calendar
Chores
Meals
Nova

Current snapshot

What exists right now.

The foundation is built across Supabase, the web companion, and Android. The setup loop is ready for local testing end to end.

Supabase backend

New project, migrations, seed invite, RLS, triggers, and RPCs for setup, settings, tablet pairing, and dashboard snapshots.

Remote migrations aligned

Phone/web companion

Vite app handles invite code validation, magic-link auth, family setup, admin settings, and tablet pairing.

Lint and build passing

Android tablet

Native app generates pairing codes, polls for claim status, persists device credentials, and boots into a live dashboard.

Debug build and unit tests passing

Product model

One family hub, two surfaces.

The wall tablet should feel permanent, glanceable, and calm. The phone/web companion is where the family manages setup and settings.

Phone/web owns setup and admin

Create the account, redeem an invite, create the family, add people, configure modules, tune Nova, invite a co-owner, and pair one or more tablets.

Android owns display and pairing

The tablet shows a 6 character pairing code, waits for the phone to claim it, stores device credentials, and then renders the kitchen display.

Target device: 27 inch Android tablet Setup order: account, family, tablet Admin changes happen on phone/web Tablet dashboard syncs from Supabase

Onboarding

The complete setup flow.

FamilySync setup starts on the phone, creates the family structure, then pairs the Android wall tablet with a short-lived code.

Invite and account

User enters the invite code, submits email, and signs in with a Supabase magic link.

Family setup

User names the family, chooses a color, adds people, selects modules, and configures Nova.

Tablet pairing

Android shows a 6 character code. The phone claims it and names the tablet, such as Kitchen.

Live dashboard

The tablet receives a device token, fetches its dashboard snapshot, and skips pairing on future launches.

Phone step 1

Invite gate

The bootstrap development invite is BETA-2026. Treat it as a development code and rotate or disable it before a public beta.

Phone step 2

Family creation

The web wizard calls create_family_setup, which redeems the invite, creates the family, owner membership, people rows, and module rows.

Tablet step

Pairing code

Android calls create_device_pairing_code. Codes are 6 characters and expire after 15 minutes.

Phone step 3

Claim tablet

Web calls claim_device_pairing_code. Supabase creates a device, marks the pairing code claimed, and binds the tablet to the family.

After claim

Device credentials

The tablet polls get_device_pairing_status, receives a device access token only when the install id matches, saves it locally, and then calls get_device_dashboard.

Architecture

How the pieces fit.

Web/

Vite mobile-web app, auth, setup wizard, admin settings, setup API wrapper, and product settings.

Android/

Native Compose tablet app, Supabase REST RPC client, pairing flow, and live dashboard shell.

supabase/

Project config, seed data, migrations, schema, RLS policies, and setup/device RPCs.

FamilySync/
  Android/
  Web/
    public/docs/
  docs/
  supabase/
  HANDOFF.md
  README.md

Supabase

Database and RPC surface.

The linked Supabase project is familysync, project ref ainhmddplbuwfhnirzkh, region us-east-1.

Main tables

profiles, invite_codes, invite_redemptions, families, family_memberships, family_people, module_catalog, family_modules, co_owner_invites, devices, and device_pairing_codes.

Main RPCs

validate_invite_code, create_family_setup, update_family_settings, create_device_pairing_code, get_device_pairing_status, claim_device_pairing_code, get_device_dashboard, and create_co_owner_invite. 

npx supabase@latest migration list
npx supabase@latest db lint --linked
npx supabase@latest db push
Do not put service role keys, database passwords, or local environment values in docs. Public anon config lives in ignored local files and should only be copied from trusted local setup notes.

Web companion

The admin surface.

The phone companion is currently a Vite app and is the source of truth for family setup and settings.

Implemented screens

Landing, invite/auth, check email, welcome, family name, members, modules, Nova setup, pair tablet, connected confirmation, live overview, and admin settings.

Admin settings

Family name/color, people, dashboard modules, Nova preferences, co-owner invite records, paired tablets, and pair-another-tablet. 

cd Web
npm install
npm run dev -- --host 0.0.0.0
npm run lint
npm run build

Android tablet

The wall display.

Android is native and downloadable. It is not intended to be the full admin surface.

Pairing

Generates a Supabase pairing code, shows it on the tablet, and polls every 3 seconds.

Persistence

Saves a local install id and paired device access token so future launches skip pairing.

Dashboard

Fetches family, people, modules, device name, Nova settings, and renders a live display shell.

cd Android
./gradlew assembleDebug testDebugUnitTest

Settings ownership

What can be changed where.

Phone/web can modify

Family name, accent color, people, roles, ages, modules, Nova name, Nova tone, kid-safe mode, co-owner invite records, and tablet pairing.

Tablet can modify

Nothing administrative yet. The tablet can generate a pairing code, connect, restore its paired session, and render the dashboard state.

Verification

Known passing checks.

cd Web
npm run lint
npm run build

cd ../Android
./gradlew assembleDebug testDebugUnitTest

cd ..
npx supabase@latest migration list
npx supabase@latest db lint --linked

Supabase smoke checks

Invite validation, pairing code creation, and pairing status polling have been tested through REST RPC calls.

Current dev server

With Vite running, this portal is available at http://localhost:5173/docs/.

Next steps

What to build after setup.

Immediate

Run the real end-to-end pairing loop

Complete web setup, launch Android, claim its code, restart Android, and confirm it opens the live dashboard.

Product

Build the first real tablet module

Calendar is the natural first module because it matches the wall display target and validates recurring daily use.

Admin

Add device management

Admins should be able to rename, remove, revoke, and eventually rotate credentials for paired tablets.

Launch

Harden auth and invites

Configure production domain, redirects, SMTP, invite lifecycle rules, and public beta code policies.