Architecture
Section 01

System overview

High-level architecture
Mobile App
Flutter (iOS · Android)
↓
Edge API
TanStack / Workers
↓
Supabase
Postgres · Auth · Storage · RLS
Core data model
User
1·N↓
Recipient
1·N↓
Occasion
1·N↓
Gift idea

Core workflows

  1. Onboarding
    Sign-up → role detect → seed sample data → guided tour
  2. Add occasion
    Pick recipient → date → budget → reminders auto-scheduled
  3. Gift planning
    Browse / discover → save idea → shortlist → purchase → mark gifted
  4. Reminders engine
    Daily cron → upcoming check → push + email + in-app feed
  5. Premium upgrade
    Paywall → RevenueCat → entitlement sync → feature flags unlock
Reminder rule engine
Occasion
−14d↓
Soft nudge
−7d↓
Push reminder
−1d↓
Urgent + email
Occasion state machine
draft
↓
upcoming
↓
planned
↓
purchased
↓
gifted

User journeys

Anya (new user) → adds Mum, sets birthday → gets 7-day reminder → buys via affiliate link
Ravi (premium) → uses Smart Match → shortlists 3 gifts → tracks budget across family
Admin → sees spike in sign-ups → publishes Christmas content → monitors retention

Operational view

Auth
Supabase Auth + RLS
Payments
RevenueCat → Stripe
Analytics
PostHog
Crashes
Sentry
CDN
Cloudflare
Search
Postgres FTS
View API documentation →