A Modular Tarot & Astrology Platform
Discover the mysteries of the cosmos through interactive tarot readings, personalized astrology charts, and immersive 3D experiences.

We are still in the early stages of development and this document is a work in progress. Some sections may be incomplete or subject to change as we refine our features and architecture.

• Live Readings: Interactive tarot card draws with AI-powered interpretations
• Spread Creator: Custom 3D tarot spreads using Babylon.js
• Card Explorer: Comprehensive tarot deck with search and filtering
• Reading Journal: Personal tarot reading history and insights

• Birth Charts: Personalized natal chart generation and analysis
• Daily Horoscopes: AI-generated daily cosmic guidance
• Transit Tracking: Real-time planetary movements and their effects
• Compatibility Analysis: Synastry charts for relationship insights

• Mystical Feed: Real-time community sharing and discussions
• Knowledge Base: Comprehensive guides to tarot and astrology
• Interactive Quizzes: Learn tarot meanings and astrological concepts
• Blog: Articles on mystical practices and cosmic events

• Astrology Dice: Quick cosmic guidance through dice divination
• Personal Calendar: Track important astrological events
• Profile Customization: Avatars, badges, and personal mystical journey
• 3D Immersive UI: Beautiful, interactive mystical environments

Mystical Realms is built as a modern, scalable monorepo with a microservices architecture:

┌─────────────────────────────────────────────────────────────┐
│                     Frontend (Next.js)                     │
│  • Server-Side Rendering    • Interactive 3D (Babylon.js)  │
│  • TypeScript Safety        • Responsive Design            │
│  • Radix UI Components      • TailwindCSS Styling          │
├─────────────────────────────────────────────────────────────┤
│                 Authentication & Database                   │
│  • Supabase Auth            • PostgreSQL Database          │
│  • Row Level Security       • Real-time Subscriptions      │
│  • OAuth Providers          • File Storage                 │
├─────────────────────────────────────────────────────────────┤
│              Backend Services (FastAPI/Python)             │
│  • Astrology Calculations   • PDF Generation               │
│  • Swiss Ephemeris          • RESTful APIs                 │
│  • Containerized Deployment • High Performance             │
└─────────────────────────────────────────────────────────────┘

• Next.js 14 - React framework with SSR/SSG
• TypeScript - Type-safe JavaScript
• Babylon.js - 3D graphics and immersive experiences
• Radix UI - Accessible, unstyled UI primitives
• TailwindCSS - Utility-first CSS framework
• React Query - Data fetching and caching
• Zustand - Lightweight state management

• FastAPI - Modern Python web framework
• Pydantic - Data validation using Python type hints
• Swiss Ephemeris - Astronomical calculations
• Docker - Containerization and deployment

• Supabase - PostgreSQL database with realtime features
• Supabase Auth - Authentication with OAuth providers
• Row Level Security - Fine-grained access control

• pnpm - Fast, disk space efficient package manager
• Jest - JavaScript testing framework
• Pytest - Python testing framework
• ESLint - Code linting and formatting
• GitHub Actions - CI/CD pipelines

Before you begin, ensure you have the following installed:

• Docker - For running Supabase locally
• Node.js (v18 or later)
• pnpm - Package manager
• Python (v3.8 or later)
• Supabase CLI (optional, for advanced database management)

1. Clone the repository

   git clone https://github.com/daemon-node-byte/MysticalRealms.git
   cd MysticalRealms

2. Install dependencies

   pnpm install

3. Start the development environment

   # Start all services (Supabase, Web, API)
   ./scripts/start_dev.sh

   Or start services individually:

   # Start Supabase (Database & Auth)
   cd packages/supabase && docker-compose up -d
   
   # or use Supabase CLI
   # supabase start
   
   # Start Next.js frontend
   pnpm dev:web
   
   # Start FastAPI backend
   pnpm dev:api

4. Access the application

   • Frontend: http://localhost:3000
   • API Documentation: http://localhost:5555/docs
   • Supabase Dashboard: http://localhost:54323

The development environment will automatically set up environment variables from .env.example files. For production deployment, ensure you configure:

• Supabase: Database URL and API keys
• OpenAI: API key for AI interpretations
• Authentication: OAuth provider credentials (optional)

Comprehensive documentation is available in the /docs/wiki directory:

• Architecture & Best Practices - Code organization and development guidelines
• Database Schema - Complete database structure and relationships
• Design Principles - UI/UX guidelines and theming
• Testing Strategy - Testing tools and methodologies
• Sprint Roadmap - Development timeline and feature priorities
• Security Policy - Security practices and vulnerability reporting
• Code of Conduct - Community guidelines and standards

# Run frontend tests
pnpm test:web

# Run backend tests
cd apps/api && pytest

# Run frontend tests with coverage
pnpm --filter web test:coverage

This project follows TDD principles:

• Frontend: Jest + React Testing Library
• Backend: Pytest + FastAPI TestClient
• E2E: Playwright for end-to-end testing
• Security: Automated security scanning in CI/CD

MysticalRealms/
├── apps/
│   ├── web/                 # Next.js frontend application
│   └── api/                 # FastAPI backend service
├── packages/
│   └── supabase/           # Database configuration and migrations
├── docs/
│   └── wiki/               # Comprehensive project documentation
├── scripts/                # Development and deployment scripts
├── docker/                 # Docker configurations
└── docs/                   # Project policies and guidelines

• apps/web/src/ - Frontend components, pages, and utilities
• apps/api/ - Backend API endpoints and business logic
• packages/supabase/ - Database schema, migrations, and seed data
• docs/wiki/ - Technical documentation and guides

• ✅ Sprint 1: Project setup and infrastructure
• ✅ Sprint 2: Authentication and user profiles
• 🔄 Sprint 3: Dashboard and core features
• ⏳ Sprint 4: Live tarot readings with AI
• ⏳ Sprint 5: Tarot explorer and journal

• Advanced Astrology: Transit predictions and aspect analysis
• Social Features: User-to-user readings and community challenges
• Mobile App: React Native companion app
• AI Enhancements: GPT-4 integration for deeper interpretations
• Marketplace: Custom tarot decks and reading templates

See the full development roadmap for detailed sprint planning.

We welcome contributions from the mystical community! Here's how to get started:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to your branch (git push origin feature/amazing-feature)
6. Open a Pull Request

• Follow the Code of Conduct
• Write tests for new features
• Update documentation as needed
• Follow the existing code style and architecture patterns
• Ensure your changes don't break existing functionality

• 🎨 UI/UX: Improve the mystical design and user experience
• 🔮 Features: Add new tarot spreads, astrological calculations
• 🧪 Testing: Expand test coverage and add E2E tests
• 📖 Documentation: Improve guides and add tutorials
• 🐛 Bug Fixes: Help us squash bugs and improve reliability
• 🌐 Localization: Translate the app to other languages

This project is licensed under the AGPL-3.0 License - see the LICENSE file for details.

Security is paramount in handling user data and mystical practices. Please review our Security Policy for:

• Vulnerability reporting procedures
• Security best practices
• Data protection measures
• Incident response protocols

To report security vulnerabilities, please email [email protected] or create a private security advisory.

• Swiss Ephemeris - For accurate astronomical calculations
• Radix UI - For accessible, unstyled UI primitives
• Supabase - For the incredible backend-as-a-service platform
• The Tarot Community - For inspiration and mystical wisdom
• Open Source Contributors - For making this project possible

If you find this project helpful, please consider giving it a ⭐ on GitHub!