Foreteller 🔮 — Wisdom of Stars & Numbers

Foreteller is a premium, full-stack analytical web application that provides deep mystical insights into a person's character based on their birth data. It combines the ancient wisdom of Numerology (Pythagoras Square), Western Astrology, Chinese Zodiac, and Lunar Cycles with cutting-edge Generative AI to deliver a comprehensive destiny profile.

---

✨ Key Features

• 🌌 Universal Wisdom: Combines Western Zodiac, Chinese Horoscope, and numerological calculations.
• 📐 Pythagoras Square: Interactive 3x3 grid visualization of personality traits derived from birth dates.
• 💞 Partner Compatibility: A dedicated mode to analyze the resonance between two individuals, including side-by-side Pythagoras square comparisons.
• 🌘 Lunar Insights: Accurate moon phase calculation for the moment of birth.
• 🤖 AI-Powered Analysis: Deep character interpretation and compatibility assessments generated by Llama-4 via Groq API.
• 📄 PDF Report Generation: Export your mystical analysis into a high-quality PDF document.
• 🌍 Multilingual Interface: Fully localized for 6 languages: English, German, French, Spanish, Ukrainian, and Russian.
• 📱 Adaptive Cosmic UI: A stunning, responsive "Cosmic Glass" design using Material UI with glassmorphism effects and modern typography.
• 🚻 Gender-Aware Predictions: Tailored AI analysis based on the selected gender for higher accuracy.

---

🛠 Technology Stack

Frontend

• React.js (v18): Core UI framework.
• TypeScript: Ensuring type safety across components.
• Vite: Ultra-fast build tool and development server.
• Material UI (v6): Advanced component library for the "Cosmic Glass" aesthetic.
• Framer Motion: Smooth micro-animations and transitions.
• html2canvas & jsPDF: Client-side PDF generation logic.

Backend

• Node.js & Express: Scalable API server.
• tsx: Direct TypeScript execution for the server.
• Axios: Handling communication with the Groq AI API.
• LunarPhase-js: Specialized library for astronomical lunar calculations.

---

🏗 Project Architecture

Foreteller/
├── client/                     # Frontend Application
│   ├── src/
│   │   ├── components/         # specialized UI: BirthForm, CompatibilityForm, PythagorasGrid, etc.
│   │   ├── constants/          # i18n & App Constants
│   │   ├── theme/              # Custom Cosmic Dark Theme (MUI)
│   │   ├── types/              # Global TypeScript Interfaces
│   │   ├── utils/              # Formatting & Translation Helpers
│   │   ├── App.tsx             # Root Application Logic & State Management
│   │   └── main.tsx            # React Mounting Point
│   └── package.json
├── api/                        # Backend Application (Express)
│   ├── index.ts                # API Routes & AI Handler
│   ├── numerology.ts           # Pythagoras Square Logic
│   ├── prompts.ts              # AI Prompt Engineering
│   └── package.json
└── README.md

---

🚀 Getting Started

Prerequisites

• Node.js (v18 or higher)
• NPM (v9 or higher)
• Groq API Key: Obtain one from Groq Cloud

Installation

1. Clone the repository

   git clone https://github.com/your-username/foreteller.git
   cd foreteller

2. Backend Setup

   cd api
   npm install

   Create a .env file in the api directory:

   PORT=3001
   GROQ_API_KEY=your_actual_api_key_here
   AI_MODEL_NAME=meta-llama/llama-4-scout-17b-16e-instruct

3. Frontend Setup

   cd ../client
   npm install --legacy-peer-deps

Running the App

Start Development Server: Open two terminals:

• Terminal 1 (Backend): cd api && npm run dev
• Terminal 2 (Frontend): cd client && npm run dev

Navigate to http://localhost:5173 (or 5174) to explore the stars.

---

🔑 API Reference

1. Personal Analysis

POST /api/analyze

Body:

Field	Type	Description
date	string	Birth date (YYYY-MM-DD)
time	string	Optional birth time (HH:mm)
place	string	Location of birth
gender	string	"male" or "female"
language	string	Language code (en, uk, ru, de, fr, es)

2. Partner Compatibility

POST /api/compatibility

Analyzes resonance between two partners.

Body:

Field	Type	Description
partner1	object	Birth data for the first partner
partner2	object	Birth data for the second partner
language	string	Language code

---

🎨 Visual Identity

The application features a Dark Cosmic theme with:

• Primary Color: Deep Purple (#a855f7)
• Secondary Color: Indigo (#6366f1)
• Compatibility Accent: Pink (#ec4899)
• Backdrop: Blur-heavy Glassmorphism cards with interactive Pythagoras square grids.
• Typography: "Outfit" for interface and "Playfair Display" for titles.

---

📝 License

Distributed under the MIT License. See LICENSE for more information.

👥 Author

Viktor Ralchenko
Full Stack Developer & Futurist

---

Created with ❤️ for the seekers of wisdom.