Technical Stack Specification: AI & Infrastructure

This document outlines the technical architecture required to power a highly personalized, conversational, and vision-enabled AI Tarot application.

🧠 1. The Intelligence Layer (LLM & NLP)

The core of the app is a highly customized, context-aware "Oracle" engine.

A. Primary Model: Large Language Model (LLM)

• Model Choice: Claude 3.5 Sonnet or GPT-4o.
• Why: These models exhibit superior reasoning, ability to follow complex symbolic instructions, and a "human-like" poetic/empathetic tone compared to smaller models.
• Role:
  • Generating personalized Tarot/Astrology interpretations.
  • Conversational interaction (The "Oracle" chat).
  • Summarizing "Emotional Arcs" from journaling data.
• Prompt Engineering Strategy:
  • System Prompt: A highly detailed "Persona" definition (The Mystic Bestie/Soul Guide).
  • Context Injection: Every prompt must include the user's Birth Chart Data (Planets, Houses, Aspects) and Current Transits.

B. Fine-Tuning & RAG (Retrieval-Augmented Generation)

• RAG Implementation: Instead of fine-tuning the entire model on Tarot, we will use a Vector Database (e.g., Pinecone or Weaviate).
• The Knowledge Base:
  • A curated, high-fidelity library of Tarot card imagery, symbolism, and historical meanings.
  • A database of astrological transits and their psychological implications.
• Workflow: When a user asks a question, the system retrieves the most relevant "symbolic context" from the vector DB and injects it into the LLM prompt.

👁️ 2. The Vision Layer (Computer Vision)

To enable "Visionary Tarot" (Scanning physical cards).

A. Model Architecture

• Model Choice: YOLO (You Only Look Once) or Segment Anything Model (SAM).
• Requirement: Real-time, low-latency detection of card boundaries and symbols.
• Logic:
  1. Detection: Identify the boundaries of multiple cards in a single camera frame.
  2. Classification: Use a lightweight, specialized classifier (or a CLIP-based embedding) to identify which of the 78 cards is present based on visual features.
  3. Mapping: Map the detected card positions to a specific "Spread Template" (e.g., Celtic Cross).

B. Implementation

• On-Device (Edge AI): For maximum speed and privacy, use CoreML (iOS) and TensorFlow Lite (Android) to run the detection model directly on the user's device. This reduces server costs and latency.

🏗️ 3. The Infrastructure & Backend

A. Backend Architecture

• Framework: NestJS (Node.js / TypeScript).
• Why NestJS over alternatives:
  • Built-in WebSocket Gateway (@WebSocketGateway) for streaming LLM token-by-token responses during the "Oracle" chat — no extra libraries.
  • First-class GraphQL module (@nestjs/graphql) with code-first schema generation, providing end-to-end type safety from Prisma models → resolvers → Expo client.
  • Dependency Injection makes it trivial to define an OracleService interface and swap LLM providers (Claude vs GPT-4o) without touching business logic.
  • Guards & Interceptors for cleanly enforcing subscription tiers (e.g., free = 1 pull/day, premium = unlimited) at the resolver/controller level.
  • Bull Queue Integration (@nestjs/bull) for offloading CPU-intensive tasks (shareable image/video rendering) to background workers.
  • Modular Architecture — features scale cleanly as isolated modules: TarotModule, AstrologyModule, NotificationModule, BillingModule, VisionModule.
• API Design: GraphQL (to allow the frontend to request only the specific parts of a massive astrological data object).
• Real-time Engine: WebSockets (via NestJS Gateway) for a seamless, streaming "Chat" experience (the Oracle "typing" its prediction).

📝 Note: If Next.js is already in the stack. If MysticX eventually ships a web companion app built with Next.js, there is no need to introduce NestJS as a separate backend. Next.js API Routes (Route Handlers) and Server Actions can serve as the API layer directly within the same codebase. This avoids deploying and maintaining two separate server processes, keeps the entire stack in a single monorepo, and simplifies authentication (shared cookies/sessions between SSR pages and API endpoints). Use NestJS only when the backend is a standalone service with no Next.js web app in the picture.

B. Data Layer

• Primary Database: PostgreSQL (via Prisma) for structured user profiles, birth charts, and subscription status.
• Vector Database: Pinecone for storing and retrieving astrological/Tarot symbolic embeddings.
• Cache Layer: Redis for rapid retrieval of daily transits and active user session data.

C. Integration Layer

• Astrology API: Integration with Swiss Ephemeris (or a provider like AstrologyAPI) to calculate real-time planetary positions.
• Health API: Integration with Apple HealthKit and Google Fit for ritual-based energy forecasting.

🛠️ 4. Frontend & Mobile Development

Framework Decision: Expo (React Native) vs. Flutter

After careful evaluation, we recommend Expo (React Native) as the mobile framework for MysticX. Below is the full comparison that informed this decision.

Comparison Table

Criteria	Expo (React Native)	Flutter
Language	TypeScript/JavaScript	Dart
Rendering	Native OEM components + Skia via react-native-skia	Custom rendering engine (Impeller/Skia) — draws every pixel
Animation Performance	Excellent with react-native-reanimated + react-native-skia	Exceptional — built-in 60/120fps engine, less boilerplate
Rive Support	Good (official SDK)	Best-in-class (deepest integration, state machines)
Cloud Builds	EAS Build — first-party, free tier, one command	Codemagic / Bitrise — third-party, paid
Store Submission	EAS Submit — single command, managed signing	Codemagic + Fastlane — more config and maintenance
OTA Updates	EAS Update — mature, push UI/copy/art changes instantly without app store review	Shorebird — young, limited, third-party
Store Metadata	EAS Metadata — localized listings managed in code	Fastlane deliver/supply — manual setup
Developer Pool	Massive (JS/TS is the world's most popular language)	Smaller (Dart is niche outside Flutter)
Web/Desktop Reuse	Share code with Next.js web dashboard via shared TS packages	Flutter Web exists but is less mature for complex web apps
Native Module Access	Full access via Expo Modules API + Config Plugins (HealthKit, native Share Sheets, etc.)	Full native access via platform channels
Cross-Platform Consistency	Minor platform-specific UI differences possible	Pixel-perfect consistency across all devices
Ecosystem Maturity	Enormous npm ecosystem	Growing pub.dev ecosystem, smaller than npm

Why Expo Wins for MysticX

1. Iteration Speed is King for a Content-Driven App. MysticX ships new daily intentions, card artwork, copy, and AI prompt tweaks constantly. Expo's OTA updates let us push these changes instantly without waiting for App Store/Play Store review cycles. Flutter has no mature equivalent — Shorebird is still early-stage.

2. Unified TypeScript Stack. The backend (Node.js/TypeScript), the AI prompt engineering layer, and the mobile app all share one language. This eliminates context-switching, enables shared validation logic (e.g., birth chart schemas), and makes hiring significantly easier.

3. EAS is a Massive DX Advantage. In Flutter, you stitch together Codemagic + Fastlane + Shorebird to approximate what Expo gives you with eas build, eas submit, and eas update. Fewer moving parts = fewer things that break on release day.

4. Animation Gap Has Closed. With react-native-reanimated v3+ running on the UI thread and @shopify/react-native-skia providing a full Skia canvas, the animation performance gap between Expo and Flutter is now marginal for our use case (card flips, glowing auras, particle effects).

5. Future Web Expansion. When MysticX eventually launches a web companion (dashboard, marketing landing pages), sharing TypeScript code between the mobile app and a Next.js web app is trivial. Flutter Web is less battle-tested for production web experiences.

When Flutter Would Have Been the Better Choice

• If MysticX were a game-like experience with continuous 3D rendering, complex physics simulations, or required absolute pixel-perfect rendering across thousands of Android device SKUs.
• If the team was already a Dart/Flutter shop with no JS/TS experience.

Chosen Stack

• Framework: Expo (React Native) with TypeScript.
• Animation Engine: react-native-reanimated + @shopify/react-native-skia for high-performance 2D graphics, complemented by Rive for pre-built interactive vector animations (card flips, celestial movements).
• Build & Release: Expo Application Services (EAS) — Build, Submit, Update, and Metadata.
• Design System: A custom-built "Mystic Design System" featuring consistent typography, "Glassmorphic" components, and "Glow" effects.

📊 Summary of Tech Stack

Component	Technologies
LLM	Claude 3.5 Sonnet / GPT-4o
Vector DB	Pinecone / Weaviate
Computer Vision	CoreML / TensorFlow Lite
Backend	NestJS (TypeScript) / GraphQL + WebSocket Gateway
Database	PostgreSQL + Prisma
Cache	Redis
Mobile	Expo (React Native) + TypeScript
Animations	react-native-reanimated + react-native-skia + Rive
CI/CD & OTA	Expo Application Services (EAS)
Infrastructure	AWS / Google Cloud