Feature Spec: The Token Bridge (Doc 09)

Proposed snapshot-based household synchronization using temporary access tokens and explicit conflict rules.

1. User Goal

To allow a secondary user (The Chef) to access the household’s current inventory and menu on their own device with zero account-creation friction, using a simple, secure 30-day token.

2. Technical Logic: The "Snapshot" Model

A. The Data Handshake

Instead of a live, constant stream (which is battery-intensive and complex), Homey uses Snapshot Synchronization. * The Push (Owner): When the Owner updates the menu or scans a major bill, they trigger a "Sync to House." The app packages the Local Room Database into a compressed JSON snapshot and uploads it to the Cloud Bridge (Firebase). * The Pull (Chef): Upon entering the 30-day code, the Chef’s app downloads this snapshot and overwrites its local "Chef-view" database.

B. Data Payload (The "Full House" View)

The Chef receives a comprehensive dataset to ensure they can work offline: 1. The Active Inventory: Every item currently in the house. 2. The Spatial Map: Full location information (Zones, Units, and 2x2 Grid coordinates). 3. The 7-Day Menu: The complete meal plan as designed by the Owner.

3. Synchronization Rules & Conflicts

A. Conflict Resolution (The "Last-Edit" Rule)

Since two people may interact with the same item (e.g., both marking the Milk as "Used"), the system follows the Latest Timestamp Wins logic. * Every change in the local database is assigned a micro-second timestamp. * During the next sync, the cloud compares timestamps; the most recent action is saved as the "State of the House."

B. The 30-Day Persistence

Access Level: Once the code is verified, the Chef remains "Logged In" locally.
Security: The app stores the token in Encrypted Shared Preferences.
Expiry: On Day 31, the app clears the local "Chef" data and prompts for a "New Household Code" from the Owner.

4. User Interface (The Workflow)

Screen 1: The Token Generator (Owner)

A simple button in the "Household Settings" that generates a 6-digit alphanumeric code.
Action: [Share Code] button (opens WhatsApp/SMS to send to the Chef).

Screen 2: The Onboarding (Chef)

A "Join a House" button on the first-launch screen.
A numeric keypad entry for the code.
Visuals: A "Connecting to Home…" animation followed by a "Welcome Home!" success message.

5. Logic Rules & Safety

Feature	Logic Rule
Offline Mode	The Chef can mark items as "Used" while offline. These changes are queued and "Pushed" to the bridge the next time the app detects a connection.
Concurrent Users	Max of Two Active Users per house for the MVP (1 Owner + 1 Chef). This prevents complex multi-user database collisions.
Manual Refresh	A "Pull to Refresh" gesture on the Dashboard allows the Chef to manually check for a new Menu/Inventory update from the Owner.

Feature

Logic Rule

Offline Mode

The Chef can mark items as "Used" while offline. These changes are queued and "Pushed" to the bridge the next time the app detects a connection.

Concurrent Users

Max of Two Active Users per house for the MVP (1 Owner + 1 Chef). This prevents complex multi-user database collisions.

Manual Refresh

A "Pull to Refresh" gesture on the Dashboard allows the Chef to manually check for a new Menu/Inventory update from the Owner.

6. Technical Components (Android)

Local Storage: Room Persistence Library.
Cloud Bridge: Firebase Realtime Database (for token matching) and Firebase Storage (for the JSON snapshots).
Sync Manager: WorkManager (to handle background uploads/downloads without draining the battery).