ReturnReady — Your Household Returns Assistant

An Alexa+ experience prototype that helps households track return deadlines, prepare packing checklists, and coordinate drop-offs through simple conversations.

Comment

Inspiration

Online shopping makes buying effortless, but returning an item inside a busy household often fails for mundane reasons:

  • Forgotten deadlines: A return window quietly closes while the parcel sits near the front door.
  • Missing accessories: Someone packs the main item but leaves the charging cable, power adapter, or original receipt on a desk.
  • Unclear responsibility: Two family members each assume the other person is handling the drop-off.

We wanted to explore a practical, grounded Alexa+ household assistant use case: turning an intention to return a purchase into a prepared, assigned task. Our core promise is simple:

Know what is due, prepare what is needed, and decide who will handle it.

What It Does

ReturnReady (https://returnready.ensure.in/) is a web-based Alexa+ experience simulation backed by a live Supabase PostgreSQL database:

  1. Zero-Friction Isolated Household Workspace: Clicking “Try sample household” establishes an isolated Supabase-authenticated browser session and runs a transactional bootstrap (rr_bootstrap_demo) that seeds five sample purchases in INR (₹) and three assignable household member names (Me, Priya, Alex).
  2. Timezone-Accurate Deadline Windows (Asia/Kolkata): Displays active returns sorted by earliest user-recorded deadline, with filters for All active, Due soon (items due within the inclusive 7-day window), Overdue (past the recorded deadline), Ready, and Dropped off, plus case-insensitive product and merchant search.
  3. Item-Specific Packing Checklists & Derived “Ready” Status: Each return includes a suggested packing checklist (for example: Headphones, Charging cable, Receipt, and Protective packaging). Checking or unchecking steps persists immediately to Supabase via rr_set_checklist. When all checklist steps on an active item are checked, ReturnReady automatically derives the Ready to drop off state; unchecking any step removes Ready immediately.
  4. Contextual Rule-Based Alexa+ Conversation: Visitors can interact through natural requests that share the exact same application service layer as the UI controls:
    • "What needs returning this week?"
    • "Show overdue items" / "Show all returns"
    • "Prepare the headphones"
    • "What is missing?"
    • "Assign this to Priya" → Confirm / Cancel
    • "Mark the headphones dropped off" → Confirm / Cancel
  5. Version-Bound Confirmations: Every mutation proposed in conversation or UI buttons creates a pending confirmation bound to the target itemId, memberId, and expectedVersion. Confirmations expire after 5 minutes, cancel automatically if an unrelated request is entered, and revalidate the database version before writing.
  6. Honest Simulation Boundaries: ReturnReady clearly labels sample data and user-entered deadlines. It does not claim live Alexa hardware connectivity, retailer account imports, return-policy verification, courier booking, refund tracking, or external SMS/email notifications.

How We Built It

  • Google Antigravity: Used as our agentic development environment to design the architecture, author the PostgreSQL schema and Row Level Security (RLS) policies, build the React + TypeScript frontend, diagnose live self-hosted Supabase endpoints, and run our automated test suites.
  • Frontend (React 19, TypeScript 5.7, Vite 6, Zod, Lucide React): Designed with a warm linen (#FAF8F5), deep navy (#0F1E36), and rich teal (#0D7A6F) editorial interface featuring accessible 44px minimum touch targets, status badges that pair distinct icons with text labels (never relying on color alone), keyboard Escape support, and focus restoration.
  • Backend & Security (Supabase Auth, PostgreSQL, Row Level Security, PL/pgSQL RPCs):
    • Four scoped tables (rr_workspaces, rr_members, rr_returns, rr_checklist_items) with ENABLE ROW LEVEL SECURITY and policies restricted TO authenticated checking owner_user_id = (SELECT auth.uid()).
    • Composite foreign keys (workspace_id, assignee_id) (ON DELETE RESTRICT) and (workspace_id, return_id) (ON DELETE CASCADE) enforcing strict tenant boundaries at the database layer.
    • Four transactional SECURITY INVOKER RPCs: rr_bootstrap_demo(), rr_reset_demo(), rr_set_checklist(), and rr_confirm_action().

Formal Invariants Enforced

  1. Calendar-Date Deadline Window (Asia/Kolkata): Rather than dividing timestamps by $86{,}400{,}000\text{ ms}$ (which causes off-by-one errors across UTC and IST midnight boundaries), deadlines are stored as PostgreSQL DATE values. Given today's calendar date $t$ in Asia/Kolkata and a recorded deadline $d$ on an active return: $$\text{DueSoon}(d, t) \iff t \le d \le t + 7, \qquad \text{Overdue}(d, t) \iff d < t$$

  2. Derived “Ready” State: For a return with stored status $s \in {\text{planning}, \text{preparing}, \text{dropped_off}}$ and checklist steps $C = {c_1, \dots, c_n}$: $$\text{Ready}(s, C) \iff s \neq \text{dropped_off} \;\land\; |C| \ge 1 \;\land\; \forall c_i \in C,\; \text{checked}(c_i) = \text{true}$$

  3. Optimistic Concurrency on Confirmed Actions: Every update on rr_returns or rr_checklist_items increments the parent return version $v \leftarrow v + 1$. When confirming a pending action created at version $v_{\text{expected}}$, rr_confirm_action commits if and only if: $$v_{\text{db}} = v_{\text{expected}} \;\land\; (t_{\text{now}} - t_{\text{created}}) \le 300\text{ s}$$

Challenges We Ran Into

  1. Detecting Stale Confirmations After Checklist Edits: If a user asked "Assign this to Priya" and then toggled a packing checklist step before clicking Confirm, the item's preparation state had changed while the confirmation was pending. We solved this with an AFTER UPDATE PostgreSQL trigger on rr_checklist_items that touches the parent rr_returns row and increments its version, causing stale confirmations to raise SQLSTATE 40001 (CONFLICT) and request a fresh confirmation.
  2. Self-Hosted Supabase Kong & GoTrue Configuration: When connecting to our dedicated self-hosted Supabase instance (https://returnready-sb.propixer.in), we discovered that Kong's default request-termination plugin blocked /mcp with HTTP 403, and GoTrue's anonymous_users setting defaulted to false while phone_autoconfirm was true. We applied our idempotent SQL migration directly in the Supabase Studio SQL Editor and built ensureDemoSession() to attempt signInAnonymously() first with an automatic fallback to an isolated ephemeral authenticated session so every visitor receives a genuine authenticated JWT isolated by auth.uid().
  3. Preserving Prior UI State on Save Failures: To avoid false-positive checkmarks when offline, checklist toggles disable duplicate clicks while a write is in flight and only update to the new state (or display a success banner) after the PostgreSQL RPC returns the persisted record.

Accomplishments That We're Proud Of

  • Unified Conversational & UI Service Layer: Conversational prompts and UI buttons call the exact same TypeScript service functions and PostgreSQL RPCs—there is no mocked chat state diverging from database state.
  • Verified Two-Session RLS Isolation: Our automated test suite (24/24 unit and component tests + 2/2 live two-session Supabase integration tests) verifies that Session A cannot read, update, or assign members from Session B's workspace, and resetting Session A's demo leaves Session B untouched.
  • Fast Judge Onboarding: Any visitor opening https://returnready.ensure.in/ can explore a live, database-backed household workspace in under 5 seconds without an email signup wall.

What We Learned

  • Designing conversational assistants around explicit, version-checked confirmation states makes voice and chat interfaces far more trustworthy for household coordination than open-ended text generation.
  • Encoding domain invariants directly in PostgreSQL constraints and triggers (dropped_off_at IS NOT NULL iff status = 'dropped_off', composite workspace foreign keys, and monotonic row versions) eliminates entire classes of frontend synchronization bugs.

What's Next for ReturnReady

  • Optional LLM-assisted intent disambiguation layered ahead of the deterministic confirmation router.
  • Multi-user household invitations with real-time Supabase channel sync.
  • Calendar export (.ics) for scheduled return drop-offs.

Built With

Share this project:

Updates

Submission history