Approved · 2026-04-20 · Ready to build
Sri Maha Jewels — Native Android App
1 · Project summary
A premium consumer Android app for Sri Maha Jewels, Perambalur's single-store jeweller. Customers browse the catalog, save pieces they love, get push notifications when the gold rate drops, book a shop visit, and view their past purchases — all through a branded Heritage-Cream UI tuned to Swiggy-level technical polish and Bvlgari-level visual restraint.
The app is a new face on an existing body — it reuses the production backend at bill.srimahajewels.com via the already-live /api/public/* endpoints. Only 3 small new endpoints (~3 hours backend work) are needed. 95%+ of development is mobile UI.
The bar we're clearing
No Indian single-store jeweller currently has an app at this polish level. Make customers proud to show the app to friends.
2 · Decisions log
| # | Decision | Rationale |
|---|---|---|
| D1 | React Native + Expo (not native Kotlin) | Shared mental model with existing JS web stack · cross-platform for future iPhone · Expo OTA ships fixes without Play Store review · 99% of users won't feel the difference |
| D2 | Tier B scope (not minimal, not showstopper) | Ships complete experience in 4 weeks without risking AR try-on delays · premium features move to v1.1 |
| D3 | Option A — Heritage Cream | Feels like a trusted Perambalur family jeweller · warm, not cold · not intimidating like luxury boutique · not stark like editorial |
| D4 | No in-app payments in v1 | Customers view invoices/schemes but pay at shop or via WhatsApp → UPI · saves ~4 days + Razorpay KYC · moves to v1.1 |
| D5 | Reuse existing backend 100% | Zero new services · only 3 new endpoints: my-invoices, my-schemes, push-token |
| D6 | Expo Push → FCM | Free, unlimited, works out-of-the-box |
| D7 | expo-image for catalog | Built-in 100 MB disk cache · works offline · no custom code |
| D8 | Cream button default for secondaries | Blends with cream bg · warm tone-on-tone · pairs with Gold Primary on every screen |
3 · Experience pillars
Four rules every screen obeys
- Cinematic, not transactional — hero photos breathe · shared-element transitions · no urgency/countdown banners · the app creates longing, not pressure
- Warm, not cold luxury — cream bg + gold accents · Playfair serif for headlines · personal microcopy ("Welcome back, Vimal" not "Welcome, User") · emoji used gently
- Every tap feels physical — haptic feedback on every interaction · spring animations · Airbnb-style heart burst on wishlist · shimmer on gold-rate card
- Festive but restrained — Akshaya/Diwali accents via subtle gold glow and seasonal hero, never garish banners
Anti-patterns (explicit no)
- No countdown timers or "3 min left!" urgency
- No "sign up to view prices" walls
- No two high-emphasis (dark) buttons on one screen
- No fake reviews, fake "23 people viewing"
- No generic stock photos in hero — only your real catalog
Reference apps
- Swiggy/Uber engineering for technical polish (60 fps scroll, haptics, zero jank)
- Airbnb for wishlist interactions and shared-element transitions
- Cartier/Bvlgari mood for visual restraint (minus the corporate feel)
- The Apple Store app for slow, confident motion
One-sentence summary
"A Perambalur family jeweller with the technical polish of Uber and the visual restraint of Cartier — an app that makes you proud to show your friends."
4 · Information architecture
Bottom tabs (4 primary)
| Tab | Purpose |
|---|---|
| 🏠 Home | Live gold rate · greeting · hero carousel of featured collections · "just arrived" · editorial story · visit-the-shop card |
| 🛍️ Shop | Full catalog · filter chips (metal, category, price, weight) · search · sort · 2-col grid |
| ❤️ Saved | Wishlist · per-item price-alert toggle · empty state with "Browse Shop" CTA |
| 👤 Me | Profile · My Invoices · My Bookings · My Schemes · Notifications · Settings |
16 screens total
Pre-login (4): Splash · OTP phone entry · OTP verify · Quick profile
Tab screens (4): Home · Shop · Saved · Me
Push-stack (8): Product detail · Collection detail · Article view · Booking form · Invoice detail · Scheme detail · Notification inbox · Settings
Golden user journeys
- Browse → Save → Price alert → Visit (core retention loop)
- Quick festival check — gold rate → new collection → save 3 pieces → close (~90 s)
- Check past purchase — Me → My Invoices → BIS QR verification (~30 s)
- Book a shop visit — product → date/time → submit → WhatsApp confirmation (~60 s)
5 · Design system (Heritage Cream)
Colour tokens
| Token | Hex | Role |
|---|---|---|
--bg | #FAF5EB | App background (warm cream) |
--bg-tinted | #F5EDD8 | Subtle warm wash |
--surface | #FFFFFF | Product cards · inputs |
--surface-warm | #FEFBF3 | Featured cards |
--surface-cream | #FBF3DF | Gold-rate card · cream button bg |
--ink | #1A1410 | Main text · warm brown-black |
--ink-muted | #5C4E3D | Secondary text · descriptions |
--ink-subtle | #8B7B67 | Labels · metadata |
--hairline | #EBE0C8 | Borders · dividers |
--gold | #B8892A | Primary brand · prices · CTAs |
--gold-bright | #D4A843 | Highlights on dark bg |
--gold-dim | #8A6820 | Hover state · button text |
--festive | #C2410C | Akshaya/Diwali accents (sparingly) |
--success | #15803D | Rate up · paid status |
Typography scale
| Role | Font | Size | Use |
|---|---|---|---|
| Display | Playfair Display 500 | 34 px | Greeting ("Welcome back, Vimal") |
| H1 | Playfair Display 500 | 28 px | Hero titles |
| H2 | Playfair Display 500 | 22 px | Section headers |
| H3 | Playfair Display 500 | 17 px | Product names |
| Body | Inter 400 | 15 px | Paragraphs |
| Small | Inter 400 | 13 px | Metadata |
| Caption | Inter 500 | 11 px | Labels |
| Overline | Inter 700 | 10 px | "TODAY'S RATE · 22K" |
Spacing · Corners · Motion
Spacing (4-based): s1=4 · s2=8 · s3=12 · s4=16 · s6=24 · s8=32 px
Corner radii: r-sm=8 (pills) · r-md=12 (cards) · r-lg=16 · r-xl=20 (hero/modals) · r-pill=999 (buttons)
Motion curves: ease-std 320 ms (standard) · ease-emph 500 ms (hero/page enter) · ease-fast 200 ms (buttons/hover)
Button variants (5)
- Primary — gold gradient · white text · warm gold shadow. Main CTA, 1 per screen.
- Cream ⭐ default secondary — cream-tinted bg · gold-dim text. Tone-on-tone blend.
- Outline — transparent · gold border · gold-dim text. Tertiary emphasis.
- Dark — warm ink bg · gold-bright text (never white). Rare, high-drama only.
- Ghost — transparent · gold text. Links / "skip".
Pairing rule
Primary + Cream on every screen. Never two Dark on the same screen. Icons before the label for actions (Book, Call, Navigate); after for outward links ("See details →").
6 · Tech architecture
Stack
- Framework: React Native 0.76+ via Expo SDK 52+
- Router: Expo Router (file-based routing)
- Language: TypeScript
- State: React built-ins + react-query for server data
- Storage: expo-secure-store (JWT) · AsyncStorage (cache) · expo-image (photos)
- Push: expo-notifications → Expo Push → FCM
- Analytics: PostHog free tier · Errors: Sentry free tier
- Build: EAS Build · OTA: EAS Update
New backend endpoints (~3 hours total)
| Endpoint | Purpose |
|---|---|
GET /my-invoices | Past invoices filtered by customer phone |
GET /my-schemes | Active schemes + next due dates |
POST /push-token | Register/update Expo push token |
POST /price-alert | Opt into price-drop alert on product |
Push notifications — what fires when
| Event | Trigger |
|---|---|
| Welcome | Profile complete |
| New collection | Manual from owner (via WhatsApp inbox → also push) |
| Gold rate dropped | Rate crosses customer's threshold · hourly cron |
| Scheme payment due | Due date minus 3 days · daily cron |
| Invoice ready | Invoice created in billing app |
| Booking confirmed | Booking status changes |
Error handling — warm, not scary
- No internet: "You're offline — showing what we last saved"
- Backend slow: Shimmer skeleton screens, never blank
- Sold out: "Just sold — we'll notify you when similar arrives"
- OTP fails: Warm message, no red error
- App crash: "Something hiccuped — tap to retry" + auto-log to Sentry
7 · Data flow
Five critical journeys · each follows optimistic-UI + background-sync + warm-fallback
First-time login (25 s)
Phone entry → POST /auth/request-otp → WhatsApp OTP → User types code → POST /auth/verify-otp → session_token → Quick profile → POST /auth/complete-profile → JWT → SecureStore write → register push token → Home tab
Browse → Save → Price alert
Shop → catalog from cache (instant) → Product detail (shared-element transition) → ❤ tap → burst animation (optimistic) → POST /likes → Long-press → "Alert me if price drops" → POST /price-alert → Days later, rate drops → cron pushes notification → User taps push → deep-link opens Product detail directly
Book a shop visit (60 s)
Product detail → "Book a visit" → bottom sheet
→ Date (next 30 days) · Time slot · Notes → Submit
→ POST /bookings
→ Backend fires WhatsApp to you ("Priya · 4 PM Sat · Lotus Ring")
→ Push to customer: "✅ Booking confirmed"
Offline scenario
Open app with no signal → SecureStore JWT → skip login → AsyncStorage cached catalog → Shop renders → expo-image cache → photos instant → ❤ taps queued locally → "Will sync when online" → Signal returns → queue replays → all synced
View scheme due date (v1 · no payment)
Me → "💎 My Schemes" → scheme detail → "Month 7 of 12 · Next due 25 Apr · ₹5,000" → "Pay at shop or scan counter UPI QR" → [Cream: Get directions] + [Ghost: Call shop]
Payment integration · deferred
Per D4: Razorpay + UPI auto-confirm moves to v1.1 after launch adoption.
8 · Rollout plan
Four weeks to Play Store · weekly checkpoints with you
Week 1 · Foundation
- Expo + TypeScript scaffold · design tokens in code
- 4 bottom tabs (empty) · OTP login flow · SecureStore JWT
- App icon + splash (cream fade-in)
- 3 new backend endpoints live
Checkpoint
Install dev build on S25 Ultra · log in with real phone · 5 minWeek 2 · Catalog
- Home tab complete (ticker · carousel · just arrived · visit card)
- Shop tab (grid · filters · search · sort)
- Product detail (photo carousel · breakdown · Save + Book)
- Image caching · pull-to-refresh everywhere
Checkpoint
Walk through Home + Shop with real products · 10 minWeek 3 · Saved · Me · Book
- Saved tab (wishlist · price alerts)
- Me tab (profile · invoices · schemes · notifications · settings)
- Book-a-visit end-to-end
- Push notifications live · empty states · warm error toasts
Checkpoint
Full walkthrough · book test visit · verify WhatsApp · 15 minWeek 4 · Polish + launch
- Motion + haptics pass · accessibility pass · performance pass
- Analytics + Sentry wired
- Play Store assets (screenshots · feature graphic · description)
- EAS production build → submit to Google Play (2-3 day review)
Checkpoint
Google Play Console registration (₹2,500 one-time) · 30 min · I walk you throughAfter launch · v1.1 (month 2+)
- 💳 Razorpay for scheme payments (auto-confirm) — 3 days
- ✨ AR try-on (earrings camera overlay) — first in Indian jewellery — 5 days
- 🔐 Biometric login — 1 day
- 📷 Scan BIS QR — 2 days
- 💬 WhatsApp chat polish — 1 day
- 🎯 Personalized "For You" — 3 days
9 · Out of scope (v1)
- In-app payments (UPI / Razorpay / cards)
- AR try-on
- Biometric login
- Real-time chat (use WhatsApp handoff)
- Order tracking (no e-commerce · customers visit shop)
- Multi-language toggle (English only in v1; Tamil in v1.1)
- iOS (Android-first)
- Social login (Google/FB) — only WhatsApp OTP
- Referral program
- Product reviews/ratings
10 · Known risks
| Risk | Likelihood | Mitigation |
|---|---|---|
| Expo SDK update breaks mid-build | Low | Pin stable SDK version |
| Play Store rejection on first submission | Medium | Pre-check permissions, privacy policy, data-safety form |
| Real product photos needed mid-Week 2 | High | Owner photographs 15-20 pieces on white cloth · ~1 hour |
| Scope creep mid-build | Medium | Any new feature → defer to v1.1 |
| v1.1 Razorpay KYC | Low | Start signup in parallel during Week 3 |
11 · Success criteria (month 1)
- 5 trusted customers install and use the app in first week
- 80% of installed users open the app at least 3× in month 1
- 20+ wishlist items saved across users
- 3+ shop visits booked via app
- 60 fps scroll maintained on Samsung Galaxy S25 Ultra
- <1 s cold-start paint on typical 4G
- 4.5+ stars average Play Store rating (from trusted early installers)
12 · Demo references
Live on localhost during brainstorm (port 8766)
| URL | Shows |
|---|---|
| rn-vs-kotlin.html | RN vs Kotlin motion comparison (why we chose RN) |
| three-designs.html | Three design directions (A/B/C — we picked A) |
| vibe-preview.html | Home screen mockup with Option A vibe applied |
| design-system.html | Full rulebook — colours, type, spacing, buttons |
| rollout.html | 4-week visual timeline |
13 · WhatsApp brand handoff
Customer-facing WhatsApp profile (already live):
- Verified name: Sri Maha Jewels · ✅ APPROVED by Meta
- Profile photo: cropped logo with perfect green circle matching WhatsApp crop
- About: "Premium gold jewellery - Perambalur - Since 1990"
- Address: "Near Co-Optex, Thuraiyur Road, Perambalur, Tamil Nadu 621212"
- Email: vimalvishal.m@gmail.com
- Website: removed until public site launch-ready
App uses wa.me/917358046407 for chat handoff with pre-seeded product context.
14 · Approval
- Experience pillars — approved 2026-04-20
- Information architecture — approved 2026-04-20
- Design system — approved 2026-04-20
- Tech architecture — approved 2026-04-20
- Data flow — approved 2026-04-20 (payments deferred)
- Rollout plan — approved 2026-04-20
Next step
Transition to superpowers:writing-plans skill → produce concrete implementation plan (Week 1 tasks, day by day, with subagent-ready splits).
Ready to kick off Week 1?
All 6 design sections approved · spec committed to git · demos archived. Now I transition to the implementation plan — the concrete task list for building the app.