MysticX Mobile App Development Plan

Executive Summary

This document outlines the plan for building a native mobile app for MysticX, targeting both iOS and Android platforms. The app will bring the full AI tarot reading experience to mobile with native interactions, push notifications, offline capabilities, and platform-specific payment flows.

Target: iOS 15.1+ and Android 7+ (API 24+) Framework: React Native with Expo (SDK 55+) Timeline: See Phase Breakdown below.

Tech Stack
Architecture
Feature Scope
Payment Integration Strategy
UI/UX Design
Phase Breakdown
Challenges and Mitigations
Testing Strategy
App Store Submission
Post-Launch

Tech Stack

Recommended Stack

Category	Technology	Rationale
Framework	React Native + Expo (SDK 55)	Shared codebase, OTA updates, mature ecosystem. Team already uses React and TypeScript.
Language	TypeScript	Same language as web app — shared types and validation schemas.
Navigation	Expo Router (file-based)	Familiar paradigm from Next.js App Router. Deep linking built in.
State Management	Zustand	Same library as web app — potential to share store logic.
Forms	React Hook Form + Zod	Same as web. Shared validation schemas.
Styling	NativeWind v4	Tailwind CSS for React Native — familiar DX from web stack.
Animation	React Native Reanimated	Hardware-accelerated native animations (card flips, spreads).
Gesture Handling	React Native Gesture Handler	Native gesture recognition for card interactions.
AI Streaming	Server-Sent Events (SSE) via fetch	Same streaming protocol as web.
Authentication	Better Auth (REST API calls)	Reuse existing auth endpoints with token-based sessions.
In-App Purchases	RevenueCat (`react-native-purchases`)	Abstracts Apple/Google IAP complexity. Expo-compatible.
External Payments	Stripe React Native SDK	For credit pack purchases (outside IAP requirement).
Push Notifications	Expo Notifications	Unified push for iOS (APNs) and Android (FCM).
Image Handling	Expo Image	Efficient image loading with caching.
Secure Storage	expo-secure-store	Keychain (iOS) / EncryptedSharedPrefs (Android) for tokens.
Haptics	expo-haptics	Tactile feedback for card flips and reveals.
Date/Time	Luxon	Same as web app.
Analytics	Mixpanel React Native	Same analytics platform as web.
OTA Updates	EAS Update	Push JS bundle updates without app store review.
Build/Deploy	EAS Build + EAS Submit	Cloud builds for iOS and Android, automated submission.

Why Expo over Bare React Native?

EAS Build — Cloud-based builds eliminate the need for macOS CI for iOS builds
OTA Updates — Push bug fixes and feature tweaks without app store review cycles
Expo Router — File-based routing mirrors Next.js App Router, reducing learning curve
Config plugins — Native module configuration without ejecting
Expo SDK — Pre-configured modules for camera, notifications, haptics, secure storage
Development builds — Fast iteration with native module support

Why Not Flutter or Swift/Kotlin Native?

Flutter: Would require rewriting all logic in Dart. No code sharing with existing TypeScript codebase.
Native (SwiftUI/Jetpack Compose): Two separate codebases to maintain. Higher initial velocity but 2x ongoing cost. Team's expertise is in TypeScript/React.
React Native + Expo: Maximum code sharing (types, validation, utilities), single codebase, team familiarity, and Expo's managed workflow reduces devops burden for a first mobile app.

Architecture

System Overview

┌─────────────────────────────────┐
│         Mobile App (Expo)       │
│  ┌───────────┐  ┌────────────┐ │
│  │  Screens  │  │   Stores   │ │
│  │  (Router) │  │  (Zustand) │ │
│  └─────┬─────┘  └─────┬──────┘ │
│        │               │        │
│  ┌─────┴───────────────┴──────┐ │
│  │       API Client Layer     │ │
│  │  (fetch + SSE + auth)      │ │
│  └─────────────┬──────────────┘ │
│                │                │
│  ┌─────────────┴──────────────┐ │
│  │  RevenueCat │ Stripe SDK   │ │
│  │  (IAP)      │ (Credit $)   │ │
│  └─────────────┬──────────────┘ │
└────────────────┼────────────────┘
                 │
                 ▼
┌─────────────────────────────────┐
│     Existing MysticX Backend    │
│  (Next.js API + Workers + DB)  │
└─────────────────────────────────┘

Key Design Principles

API-First — The mobile app is a pure client. All business logic lives in the existing Next.js API. No new backend needed.
Shared Types — Extract shared TypeScript types into a packages/shared workspace package consumed by both web and mobile.
Token-Based Auth — Mobile uses Bearer token authentication (session tokens from Better Auth stored in Secure Store).
Offline-Aware — Reading history and Card of Day cached locally. Graceful degradation when offline.
Native Feel — Platform-specific navigation patterns, haptics, and gestures. Not a webview wrapper.

Monorepo Structure

mysticx/
├── apps/
│   ├── web/              # Existing Next.js app (moved)
│   └── mobile/           # New Expo app
│       ├── app/          # Expo Router screens
│       ├── components/   # Mobile-specific components
│       ├── hooks/        # Mobile-specific hooks
│       ├── stores/       # Zustand stores (may import from shared)
│       ├── lib/          # API client, auth, utils
│       ├── assets/       # Card images, icons, fonts
│       └── app.json      # Expo configuration
├── packages/
│   └── shared/           # Shared types, validation schemas, constants
├── prisma/               # Database schema (web only)
├── scripts/              # Workers, bots (web only)
└── package.json          # pnpm workspace root

Alternatively, if a monorepo migration is too disruptive initially, the mobile app can live in a separate repository and reference shared types via a published npm package or git submodule. The monorepo approach is recommended for long-term maintainability.

API Client Layer

A lightweight API client module wrapping fetch with:

Base URL configuration (dev/staging/prod)
Automatic Bearer token injection from Secure Store
Token refresh on 401 responses
SSE streaming support for reading delivery
Request/response type safety via shared Zod schemas
Retry logic with exponential backoff
Network connectivity awareness

typescript

// Simplified example structure
type ApiClient = {
  get<T>(path: string): Promise<T>;
  post<T>(path: string, body: unknown): Promise<T>;
  stream(path: string, onToken: (token: string) => void): Promise<void>;
};

Feature Scope

MVP (v1.0) — Core Reading Experience

Feature	Description	Priority
Authentication	Email/password + Google OAuth sign-in	P0
Home Screen	Spread selection grid, quick actions, daily card prompt	P0
Tarot Reading	Full reading flow: question → spread → cards → AI streaming	P0
Card Animations	Card flip, spread layout, and reveal animations using Reanimated	P0
Follow-Up Chat	Post-reading conversation with AI	P0
Card of the Day	Daily card draw with insights and credit claim	P0
Reading History	Scrollable history with search and filters	P0
Credit Balance	Display and manage credits	P0
Subscription Purchase	Subscribe to Gold/Diamond via IAP or Stripe	P0
Credit Pack Purchase	One-time credit purchases	P0
Push Notifications	Reading complete, weekly guidance ready, subscription events	P0
Settings	Language, theme, notification preferences	P0
Onboarding	First-launch walkthrough showing key features	P1

v1.1 — Engagement Features

Feature	Description	Priority
AI Memory View	View your AI memory facts	P1
Weekly Guidance	View and generate weekly guidance	P1
Soul Journey	View and refresh soul journey	P1
Share Readings	Social sharing with generated images	P1
Widget (iOS)	Card of the Day home screen widget	P1
Widget (Android)	Card of the Day home screen widget	P1
Haptic Feedback	Tactile feedback on card interactions	P1

v1.2 — Growth Features

Feature	Description	Priority
Friend Invitations	Referral system with shareable links	P2
In-App Notifications	Notification center dropdown	P2
Card Skin Marketplace	Browse and purchase card skins	P2
Reader Selection	Browse and unlock AI readers	P2
Blog Reader	Browse blog posts	P2
Offline Mode	Cache recent readings for offline viewing	P2
Biometric Auth	Face ID/Touch ID/Fingerprint lock	P2

Intentionally Excluded from Mobile

Feature	Reason
Admin Panel	Desktop-only. Too complex for mobile.
Feedback Submission	Use in-app review prompts instead.
Affiliate Dashboard	Low-traffic feature, web-only.
Devbox Testing	Development tool, not needed in mobile builds.

Payment Integration Strategy

This is the most complex aspect of the mobile app due to Apple and Google's IAP policies.

The IAP Policy Problem

Apple's App Store policy and Google's Play Store policy require that digital goods consumed within the app must use their respective in-app purchase systems (Apple Pay / Google Play Billing). This means:

Subscriptions (Gold/Diamond) — MUST go through Apple IAP / Google Play Billing when purchased inside the mobile app
Credit packs — These are digital goods consumed in-app, so they MUST also go through IAP when purchased inside the mobile app
Apple takes 15-30% (15% for developers earning < $1M/year via Small Business Program, 30% otherwise)
Google takes 15-30% (15% for first $1M, then 30%)

Recommended Approach: Hybrid (RevenueCat + Stripe)

RevenueCat for IAP (Subscriptions + Credit Packs in Mobile)

RevenueCat is the recommended abstraction layer for IAP because:

Single SDK for both Apple and Google stores
Server-side receipt validation — No client-side receipt forgery possible
Webhook integration — Syncs subscription status to our backend in real time
Cross-platform entitlements — If a user subscribes on iOS, their Gold/Diamond status is recognized on web and Android
Analytics dashboard — MRR, churn, trial conversion metrics
Expo compatible — react-native-purchases works with Expo Config Plugins

Stripe for Web Purchases (Existing)

Existing Stripe subscriptions created on the web continue to work. The mobile app checks the user's subscription status via our API regardless of where the purchase originated.

Implementation Architecture

┌──────────────────────────────────────────────────┐
│                   Mobile App                      │
│                                                   │
│   ┌─────────────┐        ┌─────────────────────┐ │
│   │ RevenueCat  │        │   Stripe SDK        │ │
│   │ SDK         │        │   (web purchases    │ │
│   │ (IAP)       │        │    fallback)        │ │
│   └──────┬──────┘        └──────────┬──────────┘ │
└──────────┼──────────────────────────┼────────────┘
           │                          │
           ▼                          ▼
┌──────────────────┐     ┌──────────────────────┐
│   RevenueCat     │     │  Stripe Webhooks     │
│   Backend        │     │  (existing)          │
│   (receipt       │     │                      │
│    validation)   │     │                      │
└────────┬─────────┘     └──────────┬───────────┘
         │                          │
         ▼                          ▼
┌──────────────────────────────────────────────────┐
│              MysticX Backend API                  │
│                                                   │
│   RevenueCat Webhook Handler    Stripe Webhooks   │
│   POST /api/v1/webhooks/rc      (existing)        │
│                                                   │
│   ┌──────────────────────────────────────┐        │
│   │  Unified Subscription Service        │        │
│   │  - Check RevenueCat entitlements     │        │
│   │  - Check Stripe subscriptions        │        │
│   │  - Merge into single tier status     │        │
│   └──────────────────────────────────────┘        │
└──────────────────────────────────────────────────┘

Price Parity Considerations

Mobile prices are identical to web prices. We absorb Apple/Google's 15-30% commission fees entirely to keep pricing simple and fair for users.

Product	Web Price	Mobile Price	Platform Fee (15%)	Platform Fee (30%)
Gold Monthly	$19.99	$19.99	-$3.00	-$6.00
Gold Yearly	$167.92	$167.92	-$25.19	-$50.38
Diamond Monthly	$69.99	$69.99	-$10.50	-$21.00
Diamond Yearly	$587.92	$587.92	-$88.19	-$176.38
2K Credits	$9.99	$9.99	-$1.50	-$3.00
5K Credits	$19.99	$19.99	-$3.00	-$6.00
12K Credits	$39.99	$39.99	-$6.00	-$12.00
30K Credits	$79.99	$79.99	-$12.00	-$24.00

Strategy: Apply for Apple's Small Business Program (15% commission for < $1M revenue) and Google's equivalent to minimize the margin impact. At the 15% tier, the reduced margin is acceptable as a user acquisition cost. If revenue exceeds $1M and the 30% tier kicks in, revisit this decision.

Cross-Platform Subscription Sync

When a user subscribes via IAP:

RevenueCat validates the receipt and sends a webhook to our backend
Backend updates the user's tier (FREE → GOLD or DIAMOND)
Credits are granted per the subscription plan
The user's tier is reflected across web and mobile

When a user subscribes via Stripe (web):

Stripe webhook fires (existing flow)
Backend updates the user's tier
Mobile app picks up the new tier on next API call or push notification

Cross-platform entitlement check priority:

Check RevenueCat entitlements first (mobile purchases)
Check Stripe subscription status (web purchases)
Use the highest tier if both exist (edge case: user subscribed on both platforms)

Apple IAP Specific Considerations

StoreKit 2 — RevenueCat uses StoreKit 2 on iOS 15+, which provides better APIs
Restore Purchases — Required button in settings for App Store compliance
Subscription Management — Deep link to iOS subscription settings
Free Trial — Can offer trial period through Apple's IAP system
Grace Period — Enable in App Store Connect for failed renewals
Price Consent — Handle Apple's price increase consent flow

Google Play Billing Specific Considerations

Google Play Billing Library v6+ — RevenueCat handles this
Acknowledge Purchases — Must acknowledge within 3 days or auto-refunded
User-Cancellation Survey — Google shows this automatically
Account Hold — Handle suspended state on payment failure

Revenue Recognition

Revenue flow (Mobile IAP):
  User pays $19.99 (Gold Monthly via IAP)
  → Apple/Google takes $3.00-$6.00 (15-30%)
  → MysticX receives $13.99-$16.99
  → RevenueCat is free up to $2.5K MTR, then 1% of tracked revenue

Revenue flow (Web Stripe):
  User pays $19.99 (Gold Monthly via Stripe)
  → Stripe takes $0.88 (2.9% + $0.30)
  → MysticX receives $19.11

UI/UX Design

Design Principles

Mystical, Not Gimmicky — Dark themes, subtle gradients, fluid animations. Match the web's premium feel.
Touch-First — Large tap targets (44pt minimum), swipe gestures, haptic feedback
Progressive Disclosure — Don't overwhelm. Show what's needed, reveal depth on demand.
Platform Conventions — System back gesture on iOS, material navigation on Android. Respect each OS.
Reduce to Essential — Mobile has less real estate. Every pixel must earn its place.

Tab Bar (bottom):
├── Home           # Spread grid, daily card, quick actions
├── Readings       # History, search, filters
├── Card of Day    # Daily card feature (centered, prominent)
├── Insights       # Weekly Guidance, Soul Journey, AI Memory
└── Profile        # Settings, subscription, credits, invitations

Screen Inventory

Home Tab

Home Screen — Hero card with daily greeting, spread selection grid (2 or 3 columns), "Start Reading" CTA, recent reading preview
Spread Detail — Spread description, card positions visual, example questions, "Begin" button
Reading Flow — Question input → card selection animation → streaming AI response → structured reading view
Follow-Up Chat — Conversation view with message bubbles, typing indicator, quick reply suggestions

Readings Tab

Reading History — Chronological list with search, spread type filters, date grouping
Reading Detail — Full reading with expandable sections (summary, cards, advice)
Share Preview — Share card generation with social platform pickers

Card of Day Tab (Center)

Daily Card — Full-screen card reveal with animation, daily insights, credit claim, resonance tracking
Card of Day History — Calendar view of past daily draws

Insights Tab

Insights Overview — Cards for Weekly Guidance, Soul Journey, AI Memory
Weekly Guidance — Formatted guidance with generate/refresh button
Soul Journey — Personal evolution narrative with theme tags
AI Memory — List of 5 memory facts with explanations

Profile Tab

Profile — Avatar, name, email, tier badge, credit balance
Subscription — Current plan details, upgrade/manage buttons, billing history
Credits — Balance, transaction history, purchase packs
Invitations — Referral code, share button, invited users list
Settings — Language, theme (light/dark/system), notifications, app info
Marketplace — Card skins browser, reader unlock gallery

Card Interaction Design

The card interaction is the centerpiece of the app and must feel magical:

Card Deck — 3D-perspective fan of face-down cards
Card Selection — Drag or tap to select; selected cards float up with haptic pulse
Card Flip — 3D flip animation using Reanimated's shared values (60fps)
Spread Layout — Cards animate into spread position (Celtic Cross, diamond, etc.)
Card Zoom — Tap a card to see full details in a bottom sheet

Streaming Reading Display

AI response streams into a scrolling view with markdown rendering
Section headers (Summary, Card 1, Card 2, Advice) appear progressively
Subtle fade-in animation for each new token batch
Auto-scroll follows the latest content
"Done" haptic when streaming completes

Dark Mode

The app should default to dark mode (consistent with the mystical theme) but support light mode and system preference. Color tokens should mirror the web app's CSS custom properties.

Typography

Primary: System font (SF Pro on iOS, Roboto on Android)
Accent: A serif font for card names and reading titles (e.g., Playfair Display or similar)
Body: System sans-serif for readability

Offline Experience

Recently viewed readings are cached in AsyncStorage
Card of Day results cached for today
Spreads and question categories cached on first load
Offline state: banner at top, disabled actions for network-dependent features
Automatic retry when connection restores

Phase Breakdown

Phase 0: Foundation (Week 1-2)

Set up Expo project with TypeScript and EAS
Configure Expo Router with tab navigation
Set up NativeWind v4 with design tokens matching web theme
Implement API client layer with auth token management
Set up Secure Store for token persistence
Configure Mixpanel React Native
Set up EAS Build profiles (development, preview, production)
Create shared types package (or establish type sharing approach)

Phase 1: Authentication (Week 2-3)

Sign-in screen (email/password)
Sign-up screen with email verification
Google OAuth sign-in (Expo AuthSession)
Session management with automatic token refresh
Protected route handling in Expo Router
Password reset flow

Phase 2: Core Reading Experience (Week 3-6)

Home screen with spread selection grid
Spread detail screens
Question input with character counter
Card selection animation (the "money shot")
AI reading streaming screen
Structured reading display with markdown
Follow-up chat interface
Reading history list with filters
Reading detail view
Credit balance display and deduction UI

Phase 3: Card of the Day (Week 6-7)

Daily card screen with reveal animation
Insights display (emotional weather, actions, questions)
Credit claim flow
Resonance tracking
Card of Day history

Phase 4: Payments (Week 7-9)

RevenueCat setup and product configuration
Apple App Store product creation (subscriptions + consumables)
Google Play Store product creation (subscriptions + consumables)
Subscription purchase flow (IAP)
Credit pack purchase flow (IAP)
Cross-platform subscription sync via webhooks
Subscription management screen
Restore purchases flow
Backend webhook handler for RevenueCat events
Price testing and verification on both platforms

Phase 5: Push Notifications (Week 9-10)

Expo Notifications setup (APNs + FCM)
Push token registration on backend
Notification types: reading complete, guidance ready, daily reminder, subscription events
Notification preferences screen
Deep linking from notifications to specific screens
Badge count management

Phase 6: Polish and Platform (Week 10-12)

Onboarding flow (3-4 screens)
Haptic feedback on all card interactions
Landscape lock (portrait only)
App icon and splash screen
Settings screen (language, theme, notifications)
Error boundaries and crash reporting
Performance optimization (list virtualization, image caching)
Accessibility audit (VoiceOver, TalkBack)
Tablet layout adaptations (iPad, Android tablets)

Phase 7: Testing and Submission (Week 12-14)

End-to-end testing on physical devices
IAP testing on TestFlight (iOS) and Google Play Internal Testing (Android)
App Store screenshot generation
App Store metadata (descriptions, keywords) in all supported languages
Apple App Store submission
Google Play Store submission
App Review preparation (demo account, review notes)

Phase 8: Post-Launch Features (Week 15+)

iOS widget (Card of Day)
Weekly Guidance and Soul Journey screens
AI Memory view
Friend invitation system
Card skin marketplace
Share readings feature
Biometric authentication
Offline mode improvements

Challenges and Mitigations

1. Apple App Store Review

Challenge: Apple is strict about digital content apps using IAP. They may also scrutinize "fortune telling" apps more closely.

Mitigation:

Frame the app as "AI-powered self-reflection and mindfulness" rather than "fortune telling"
Ensure all digital purchases go through IAP
Include clear disclaimers that readings are for entertainment/reflection purposes
Prepare a demo account with credits for the review team
Study App Store Review Guidelines Section 5.3 (Gaming, Gambling, and Lotteries) — tarot should be fine as it's not gambling, but be prepared for questions

2. Payment Complexity

Challenge: Managing two payment systems (RevenueCat for IAP + Stripe for web) with unified subscription status.

Mitigation:

RevenueCat's webhook integration makes this manageable
Create a unified subscription service in the backend that checks both sources
Use RevenueCat's customer attributes to link to MysticX user IDs
Implement "Restore Purchases" prominently for users switching devices
Test cross-platform scenarios thoroughly (subscribe on web, verify on mobile, and vice versa)

3. SSE Streaming on Mobile

Challenge: Server-Sent Events have varying support on mobile. Background execution limits may kill long-running connections.

Mitigation:

Use fetch with ReadableStream for SSE parsing (works in React Native's new architecture)
Implement reconnection logic if the stream drops
Add a fallback polling mechanism that checks reading status every 2 seconds
Keep the app in the foreground during readings (prevent screen sleep)
Show a "Reading in progress" push notification if the app is backgrounded during generation

4. Card Animations Performance

Challenge: Complex 3D card flip and spread layout animations must run at 60fps on lower-end Android devices.

Mitigation:

Use React Native Reanimated (runs on the UI thread, not JS thread)
Use expo-image for optimized card image loading with disk caching
Pre-load card images during spread selection
Reduce animation complexity on lower-end devices (detect with device info)
Profile with Flipper and Android Studio Profiler during development

5. Offline and Network Resilience

Challenge: Mobile users frequently switch between WiFi, cellular, and offline states.

Mitigation:

Use @react-native-community/netinfo for connection monitoring
Implement optimistic UI for non-critical actions
Queue failed requests for retry when connection returns
Cache reading history, Card of Day, and spread data locally
Show clear offline indicators without blocking the entire app

6. i18n with 12 Locales

Challenge: Significant translation workload for mobile-specific strings.

Mitigation:

Reuse existing translation dictionaries where possible (shared types/constants)
Use the same useTrans pattern from the web app adapted for React Native
Start with English + Chinese (largest user base), add other locales incrementally
Use AI translation as a first pass, then human review

7. Image Assets and Bundle Size

Challenge: Card images (78 cards x multiple skins) could balloon the bundle size.

Mitigation:

Do NOT bundle card images. Load from CDN (Cloudflare R2) with aggressive caching
Use expo-image with placeholder and cachePolicy: 'disk'
Implement progressive loading: show card backs immediately, load face images on demand
Compress images server-side (WebP format with Sharp)
Default card skin images cached on first launch (~5 MB)

8. App Size

Challenge: Expo apps can be large if not optimized (~50 MB+ baseline).

Mitigation:

Enable Hermes JS engine (default in Expo 55)
Use ProGuard (Android) and bitcode stripping (iOS)
Tree-shake unused Expo modules
Target < 80 MB total app size

Testing Strategy

Unit Tests

Shared validation schemas (Zod)
API client layer
Credit calculation logic
State management stores

bash

npx jest

Component Tests

React Native Testing Library for component rendering
Snapshot tests for key screens
Interaction tests for card selection and form flows

E2E Tests

Detox (or Maestro) for end-to-end testing
Critical paths: sign-in → reading → follow-up → history
IAP flows tested on physical devices

Payment Testing

RevenueCat Sandbox (Apple) and Testing API (Google)
Stripe Test Mode for web payment fallback
Cross-platform subscription scenarios:
- Subscribe on iOS → verify on Android
- Subscribe on web → verify on mobile
- Cancel on one platform → verify status update

Beta Testing

TestFlight (iOS) — 10,000 external testers
Google Play Internal Testing → Closed Testing → Open Testing
Internal team testing for 2 weeks before submission
Staged rollout: 10% → 50% → 100%

Device Matrix

Minimum test coverage:

iOS	Android
iPhone SE (3rd gen)	Pixel 7a
iPhone 14	Samsung Galaxy A54
iPhone 16 Pro Max	Samsung Galaxy S24
iPad Air (5th gen)	Google Pixel Tablet

App Store Submission

Apple App Store

Requirements:

Apple Developer Program ($99/year)
App Store Connect account
Screenshots for all required device sizes (6.7", 6.5", 5.5" for iPhone; 12.9" for iPad)
App Privacy Nutrition Labels
App Tracking Transparency (ATT) prompt if using advertising analytics
Age rating: 4+ (tarot as entertainment is not age-restricted in most countries)

Metadata (Prepare in all 12 locales):

App name: "MysticX - AI Tarot Reader"
Subtitle: "Personalized Tarot Readings"
Description: Focus on AI-powered self-reflection, mindfulness, and personal growth
Keywords: tarot, ai, reading, horoscope, daily, card, spiritual, mindfulness, self-care
Category: Lifestyle (primary), Entertainment (secondary)

Review Notes:

Provide demo account with sufficient credits
Explain that the app provides AI-generated insights for personal reflection
Note that all digital purchases use IAP
Include links to privacy policy and terms of service

Google Play Store

Requirements:

Google Play Developer account ($25 one-time fee)
Play Console access
Screenshots for phone and tablet
Data Safety section

Listing Quality:

Feature graphic (1024x500)
Short description (80 chars max)
Full description
Content rating questionnaire
Target audience declaration

Post-Launch

Monitoring

Sentry or Expo Error Reporting for crash tracking
RevenueCat Dashboard for IAP metrics (MRR, churn, trial conversion)
Mixpanel for user engagement metrics (DAU, retention, reading completion rate)
App Store Connect Analytics and Google Play Console for install/uninstall metrics

OTA Updates

Expo EAS Update allows pushing JS bundle updates without a full app store review. Use this for:

Bug fixes
Copy/text changes
New spread data
Feature flag toggleups

Native changes (new modules, SDK version bumps) still require a full build and store submission.

Iteration Plan

Weekly: Monitor crash rates, fix critical bugs via OTA
Bi-weekly: Review analytics, prioritize feature backlog
Monthly: App store update with feature additions
Quarterly: Major version with significant new features

Key Metrics to Track

Metric	Target
Day 1 Retention	> 40%
Day 7 Retention	> 20%
Day 30 Retention	> 10%
Reading Completion Rate	> 80%
Daily Active Readings	> 2 per active user
Free → Paid Conversion	> 5%
Trial → Subscription	> 30%
App Store Rating	> 4.5 stars
Crash-Free Rate	> 99.5%

Competitor Analysis Notes

Tarot Apps on App Store (Key Observations)

Labyrinthos — Clean minimalist UI, educational focus. Free with IAP for advanced features. 4.8 stars.
Golden Thread Tarot — Same developer as Labyrinthos. Beautiful card art, journal feature. 4.7 stars.
Galaxy Tarot — Android-first, traditional look. Ad-supported with premium tier. 4.5 stars.
Mystic Mondays — Modern art style, wellness-focused branding. Subscription model. 4.6 stars.
The Pattern — Not tarot, but similar "personalized insights" concept. Very successful with push notifications. 4.6 stars.

What Users Expect (Based on App Store Reviews)

Beautiful card art and animations — The visual experience IS the product
Fast, accurate readings — Users are impatient; streaming helps here
Daily engagement hook — Card of Day is the retention driver (most competing apps have this)
Journal/history — Users want to track their readings over time
No aggressive paywalls — Let users experience value before asking for money
Offline basics — View past readings without internet
Privacy — Users share very personal questions. Be transparent about data handling.

MysticX Differentiators

AI-powered personalization — Most competitors use static card meanings. MysticX's Gemini integration provides truly unique, contextual readings
AI Memory — No competitor learns from past readings
Interactive follow-ups — Most apps are one-directional. MysticX allows conversation with the reader
Multiple AI reader personas — Unique personalities, not just generic interpretations
13 spreads — Most competitors offer 3-5 spreads
Cross-platform — Seamless experience across web, mobile, and Telegram

Budget Estimates

Item	Cost	Frequency
Apple Developer Program	$99	Annual
Google Play Developer	$25	One-time
RevenueCat	Free (< $2.5K MTR), then 1%	Monthly
EAS Build (Expo)	Free tier (30 builds/mo), $99/mo for more	Monthly
Sentry (crash reporting)	Free tier (5K events), $26/mo for Team	Monthly
Design (app icon, splash, screenshots)	$500-$2,000	One-time
App Store Optimization (ASO)	$0 (DIY) or $500-$2,000 (agency)	One-time

Open Questions

Monorepo vs. Separate Repo? — Monorepo is recommended but requires migrating the existing web app into apps/web/. A separate repo is simpler to start but harder to share code.
RevenueCat vs. expo-iap? — RevenueCat adds a service dependency but dramatically simplifies IAP. expo-iap is lower-level. Recommendation: RevenueCat for a first mobile app.
~~Should mobile prices be higher than web?~~ — Decided: Keep mobile prices identical to web. We absorb platform fees entirely as a user acquisition cost. Apply for Apple/Google Small Business Programs to reduce to 15%.
Launch markets? — Should we launch globally on day one or start with specific markets? Recommendation: Global launch (we already support 12 languages).
Free trial via IAP? — Apple/Google support free trial periods for subscriptions. Should we offer 7-day free trial on mobile? Recommendation: Yes, with a 7-day trial for Gold and a 3-day trial for Diamond.
App name? — "MysticX" is short and memorable. Should the App Store name be "MysticX" or "MysticX - AI Tarot Reader" for better discoverability? Recommendation: "MysticX - AI Tarot Reader" for ASO, with "MysticX" as the short name under the icon.

MysticX Mobile App Development Plan ​

Executive Summary ​

Table of Contents ​

Tech Stack ​

Recommended Stack ​

Why Expo over Bare React Native? ​

Why Not Flutter or Swift/Kotlin Native? ​

Architecture ​

System Overview ​

Key Design Principles ​

Monorepo Structure ​

API Client Layer ​

Feature Scope ​

MVP (v1.0) — Core Reading Experience ​

v1.1 — Engagement Features ​

v1.2 — Growth Features ​

Intentionally Excluded from Mobile ​

Payment Integration Strategy ​

The IAP Policy Problem ​

Recommended Approach: Hybrid (RevenueCat + Stripe) ​

RevenueCat for IAP (Subscriptions + Credit Packs in Mobile) ​

Stripe for Web Purchases (Existing) ​

Implementation Architecture ​

Price Parity Considerations ​

Cross-Platform Subscription Sync ​

Apple IAP Specific Considerations ​

Google Play Billing Specific Considerations ​

Revenue Recognition ​

UI/UX Design ​

Design Principles ​

Navigation Structure ​

Screen Inventory ​

Home Tab ​

Readings Tab ​

Card of Day Tab (Center) ​

Insights Tab ​

Profile Tab ​

Card Interaction Design ​

Streaming Reading Display ​

Dark Mode ​

Typography ​

Offline Experience ​

Phase Breakdown ​

Phase 0: Foundation (Week 1-2) ​

Phase 1: Authentication (Week 2-3) ​

Phase 2: Core Reading Experience (Week 3-6) ​

Phase 3: Card of the Day (Week 6-7) ​

Phase 4: Payments (Week 7-9) ​

Phase 5: Push Notifications (Week 9-10) ​

Phase 6: Polish and Platform (Week 10-12) ​

Phase 7: Testing and Submission (Week 12-14) ​

Phase 8: Post-Launch Features (Week 15+) ​

Challenges and Mitigations ​

1. Apple App Store Review ​

2. Payment Complexity ​

3. SSE Streaming on Mobile ​

4. Card Animations Performance ​

5. Offline and Network Resilience ​

6. i18n with 12 Locales ​

7. Image Assets and Bundle Size ​

8. App Size ​

Testing Strategy ​

Unit Tests ​

Component Tests ​

E2E Tests ​

Payment Testing ​

Beta Testing ​

Device Matrix ​

App Store Submission ​

Apple App Store ​

Google Play Store ​

Post-Launch ​

Monitoring ​

OTA Updates ​

Iteration Plan ​

Key Metrics to Track ​

Competitor Analysis Notes ​

Tarot Apps on App Store (Key Observations) ​

What Users Expect (Based on App Store Reviews) ​

MysticX Differentiators ​

MysticX Mobile App Development Plan

Executive Summary

Table of Contents

Tech Stack

Recommended Stack

Why Expo over Bare React Native?

Why Not Flutter or Swift/Kotlin Native?

Architecture

System Overview

Key Design Principles

Monorepo Structure

API Client Layer

Feature Scope

MVP (v1.0) — Core Reading Experience

v1.1 — Engagement Features

v1.2 — Growth Features

Intentionally Excluded from Mobile

Payment Integration Strategy

The IAP Policy Problem

Recommended Approach: Hybrid (RevenueCat + Stripe)

RevenueCat for IAP (Subscriptions + Credit Packs in Mobile)

Stripe for Web Purchases (Existing)

Implementation Architecture

Price Parity Considerations

Cross-Platform Subscription Sync

Apple IAP Specific Considerations

Google Play Billing Specific Considerations

Revenue Recognition

UI/UX Design

Design Principles

Navigation Structure

Screen Inventory

Home Tab

Readings Tab

Card of Day Tab (Center)

Insights Tab

Profile Tab

Card Interaction Design

Streaming Reading Display

Dark Mode

Typography

Offline Experience

Phase Breakdown

Phase 0: Foundation (Week 1-2)

Phase 1: Authentication (Week 2-3)

Phase 2: Core Reading Experience (Week 3-6)

Phase 3: Card of the Day (Week 6-7)

Phase 4: Payments (Week 7-9)

Phase 5: Push Notifications (Week 9-10)

Phase 6: Polish and Platform (Week 10-12)

Phase 7: Testing and Submission (Week 12-14)

Phase 8: Post-Launch Features (Week 15+)

Challenges and Mitigations

1. Apple App Store Review

2. Payment Complexity

3. SSE Streaming on Mobile

4. Card Animations Performance

5. Offline and Network Resilience

6. i18n with 12 Locales

7. Image Assets and Bundle Size

8. App Size

Testing Strategy

Unit Tests

Component Tests

E2E Tests

Payment Testing

Beta Testing

Device Matrix

App Store Submission

Apple App Store

Google Play Store

Post-Launch

Monitoring

OTA Updates

Iteration Plan

Key Metrics to Track

Competitor Analysis Notes

Tarot Apps on App Store (Key Observations)

What Users Expect (Based on App Store Reviews)

MysticX Differentiators