A sacred space for reflection, powered by advanced AI and Glassmorphism.
Bridging ancient wisdom with modern software architecture.
Tarots OS is a premium, privacy-focused Tarot journal. It transforms the smartphone into a digital altar, offering a sacred space for daily reflection powered by introspection-tuned AI interpretations and a cutting-edge Glassmorphic interface.
Tarots OS follows a "Ritualistic UX" approach. Every interaction is designed to feel weighty and meaningful.
- 💎 Glassmorphism: Deep utilization of
expo-blurand multi-layered translucency creates a sense of depth and ethereal beauty. - 📳 Tactile Feedback: Full integration of
expo-hapticsprovides physical "clinks" during card flips and "pulses" during cosmic RNG draws. - 🌗 Immersive Atmosphere: Dynamic light/dark mode support with semantic color mapping ensures accessibility while maintaining the mystical vibe.
- 🌊 Micro-interactions: Fluid layout transitions using
LayoutAnimationand shared element logic for an organic feel.
| Daily Ritual | Deck Gallery | The Spread | AI Gnosis |
|---|---|---|---|
 |
 |
 |
 |
Tarots OS is currently in active development. We are preparing for a public release on all major open platforms.
- 🔮 AI-Powered Insights: Uses advanced LLMs (via OpenRouter) with custom "System Prompts" to provide psychological and evolutionary interpretations, avoiding fatalistic predictions.
- 📖 The Chronicles: A local-first journal to track your spiritual journey over time, searchable by keywords, suits, or feelings.
- 🃏 Deck Explorer: A "Sacred Library" to study the visual and esoteric details of the Rider Waite Smith deck.
- 🛠️ Customizable Rituals: Toggle between Full Deck and Major Arcana, handle reversals, and set personal intentions.
- 🔒 Privacy First: Your journal lives on your device (AsyncStorage). No servers, no tracking. JSON export available for your data sovereignty.
Engineered for scalability, maintainability, and performance.
- Framework: React Native via Expo SDK 50+
- Language: TypeScript (Strict Mode)
- State Management: Zustand + AsyncStorage for persistence.
- UI Framework: React Native Paper (Heavily customized theme).
- AI Layer: Agnostic Service Layer connecting to OpenRouter/OpenAI Compatible.
A Data-Driven approach allows for easy addition of new decks and spreads without touching the core logic.
src/
├── components/ # Atomic UI (GlassSurface, CardFlip, Modals)
├── data/ # JSON Definitions (Spreads, Decks)
├── features/ # Screens (Reading, History, Settings)
├── hooks/ # Business Logic (useDailyDraw, useInterpretation)
├── services/ # RNG Engine, Storage, DeckRegistry
├── store/ # Zustand Stores
└── types/ # TypeScript Interfaces
-
Clone the Repository
git clone https://github.com/lorenzomaiuri-dev/tarots-os.git cd tarots-os -
Install Dependencies
npm install
-
Prepare Assets (Copyright Compliance) High-res Rider Waite images are not included in the repo.
- Place your images in
assets/rider-waite/(format:maj_00.jpg,wands_01.jpg...). - Run the hydration script:
node scripts/generate-deck.js rider-waite
- Place your images in
-
Run the App
npx expo start
-
Ignition Follow the in-app Onboarding to insert your API Key.
- v1.0: Core Engine, History, AI Integration
- v1.1: Home Screen Widgets & Notifications
- v2.0: Multi-deck comparison & "Study Mode"
Contributions are welcome. Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.
Distributed under the MIT License. See LICENSE for more information.
- A.E. Waite & Pamela Colman Smith for the timeless imagery.
- OpenRouter for democratizing access to LLMs.
- The React Native community for the tools to build beautiful software.
Crafted with 💜 and Intention.