Decide My Life: Numerology

An iOS numerology app with a "Paperwhite Gazette" design — a personal daily number newspaper. Flutter client, Node.js/OpenRouter (Claude) backend on Railway, Firebase, Meta Ads tracking.

Repository layout

numerology-app/
├── app/                          # Flutter iOS app
│   ├── lib/
│   │   ├── core/                 # theme, haptics, widgets, router, config
│   │   ├── data/                 # profile, api client, insight service, local content
│   │   ├── features/             # onboarding, home, chat, numbers, compatibility, paywall
│   │   └── main.dart
│   └── packages/numerology_engine # pure-Dart calculation engine (+ tests)
├── backend/                      # Node.js + Hono + Vercel AI SDK + OpenRouter (Railway)
├── assets-pipeline/              # fal.ai build-time engraving generator
├── PLAN.md                       # full product/technical plan
└── SETUP.md                      # go-live runbook (Firebase/Facebook/RevenueCat/Railway)

Status

Area	State
Numerology engine (Dart + TS port)	✅ built, unit-tested (21 + 7 tests)
Paperwhite Gazette design system	✅ built, verified on simulator
Onboarding (ATT-first, reveal, paywall)	✅ built
Home (Today's Gazette) + number detail	✅ built, verified
AI question sheet (streaming)	✅ built (uses backend when configured)
Backend (insight/ask/report/compatibility)	✅ built, typechecked, tested
fal.ai asset pipeline	✅ built (run with FAL_KEY)
Firebase / Facebook / RevenueCat	🔑 architected behind seams — activate per SETUP.md when keys land

The app runs today fully on-device: numerology is computed locally, and daily readings use a built-in content fallback. It automatically upgrades to Claude-generated content once API_BASE_URL points at the deployed backend.

Run the app

cd app
flutter pub get
flutter run                                   # on-device fallback content
flutter run --dart-define=API_BASE_URL=https://your.up.railway.app   # with Claude
flutter run --dart-define=DEMO=true           # seed a demo profile → straight to home

Run the backend locally

cd backend
npm install
cp .env.example .env    # set OPENROUTER_API_KEY, AUTH_DISABLED=true for local
npm run dev

Tests

cd app/packages/numerology_engine && dart test   # engine
cd app && flutter test                           # widget smoke test
cd backend && npx vitest run                     # backend engine parity

Key decisions (see PLAN.md for rationale)

• Flutter over Expo — render quality for the letterpress/animation bar.
• OpenRouter (not the Anthropic API directly) for Claude access.
• ATT prompt at launch, before onboarding, to maximize Meta attribution.
• US / English only for v1.
• Deterministic math on-device; Claude only for interpretation → low API cost.
• App Store title note: ship title Decide My Life: Numerology (fits 30-char limit) + subtitle Daily Numerology Analysis (US spelling).