An AI-powered astrological prediction engine combining KP, Vedic, Vodou, Rosicrucian, and Arabic methodologies

🎯 New Vision (Nov 2025): This project has pivoted from a frontend-focused web app to an AI-first prediction engine. We're building the most accurate astrological prediction system by synthesizing multiple traditions through AI.

Input: Birth data + Life question (e.g., "When will I get married?")

Output: Precise prediction with:

• ✅ Timing windows (specific dates/periods)
• ✅ Confidence score (0-100%)
• ✅ Multi-tradition reasoning (KP, Vedic, Vodou, Rosicrucian, Arabic)
• ✅ Spiritual remedies (rituals, meditations, offerings)
• ✅ Supporting evidence from each tradition

Example Query:

{
  "birth_data": {
    "date": "1990-08-15",
    "time": "14:30",
    "location": { "lat": 29.7604, "lon": -95.3698 }
  },
  "question": "When will I get a job promotion?"
}

Example Response:

{
  "prediction": "Job promotion highly likely Nov 2025 - Jan 2026",
  "confidence": 0.87,
  "timing_windows": [
    {
      "start": "2025-11-15",
      "end": "2026-01-30",
      "optimal_dates": ["2025-11-22", "2025-12-13"]
    }
  ],
  "reasoning": {
    "kp": "10th cusp sub-lord Jupiter activates in Venus transit",
    "vedic": "Venus-Rahu dasha supports career elevation",
    "vodou": "Ogou (Mars) + Erzulie (Venus) activation period",
    "rosicrucian": "Venus-Jupiter hours optimal for negotiations"
  },
  "remedies": [
    {
      "tradition": "Vodou",
      "action": "Ogou altar offering",
      "timing": "Tuesday Mars hour"
    },
    {
      "tradition": "Vedic",
      "action": "Venus mantra 108x",
      "timing": "Friday mornings"
    }
  ]
}

• Swiss Ephemeris: JPL-precision astronomical calculations
• Python 3.14: Core KP/Vedic calculation engine
• KP Engine: Sub-lord calculator (249 subdivisions per sign) ✅ WORKING
• Nakshatra Calculator: 27 lunar mansions with psychological profiles

• LangChain: AI orchestration framework
• OpenAI GPT-4 / Anthropic Claude: Natural language synthesis
• ChromaDB / Pinecone: Vector database for knowledge base RAG
• Knowledge Base: 72+ astrology books for prediction validation

• Flask / FastAPI: Python API server
• PostgreSQL 14+: Birth chart storage, prediction logging
• REST API: Simple /predict endpoint (no frontend initially)

• Git: Version control
• pytest: Python testing framework
• Docker (future): Containerization
• CI/CD (future): Automated testing

• Node.js: v18.0.0 or higher
• npm: v9.0.0 or higher
• PostgreSQL: v14.0 or higher
• Git: v2.30 or higher

node --version  # Should be v18+
npm --version   # Should be v9+
psql --version  # Should be v14+
git --version   # Should be v2.30+

git clone https://github.com/Thelastlineofcode/Astrology-Synthesis.git
cd Astrology-Synthesis

# Start PostgreSQL service
# macOS (Homebrew):
brew services start postgresql@14

# Linux (Ubuntu/Debian):
sudo systemctl start postgresql

# Create database and user
psql postgres

In the PostgreSQL console:

CREATE DATABASE roots_revealed_db;
CREATE USER roots_revealed_user WITH ENCRYPTED PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE roots_revealed_db TO roots_revealed_user;
\q

cd backend

# Copy environment file
cp .env.example .env

# Edit .env with your database credentials
nano .env  # or use your preferred editor

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Start development server
npm run dev

Backend will run on: http://localhost:5000

cd ../frontend

# Copy environment file
cp .env.local.example .env.local

# Install dependencies
npm install

# Run tests
npm test

# Start development server
npm run dev

Frontend will run on: http://localhost:3000

Roots-Revealed/
├── backend/                    # Node.js/Express API
│   ├── src/
│   │   ├── config/            # Configuration files
│   │   ├── controllers/       # Request handlers
│   │   ├── middleware/        # Express middleware
│   │   ├── models/            # Database models
│   │   ├── routes/            # API routes
│   │   ├── services/          # Business logic
│   │   ├── types/             # TypeScript types
│   │   ├── utils/             # Utility functions
│   │   ├── __tests__/         # Tests
│   │   └── index.ts           # Entry point
│   ├── dist/                  # Compiled JavaScript
│   ├── .env.example           # Environment template
│   ├── package.json
│   ├── tsconfig.json
│   └── jest.config.js
│
├── frontend/                   # Next.js Application
│   ├── src/
│   │   ├── app/               # Next.js App Router
│   │   │   ├── __tests__/     # Page tests
│   │   │   ├── layout.tsx     # Root layout
│   │   │   ├── page.tsx       # Home page
│   │   │   └── globals.css    # Global styles
│   │   ├── components/        # React components
│   │   ├── lib/               # Utility libraries
│   │   └── types/             # TypeScript types
│   ├── public/                # Static assets
│   ├── .env.local.example     # Environment template
│   ├── package.json
│   ├── tsconfig.json
│   ├── tailwind.config.ts
│   └── jest.config.ts
│
├── .env.example               # Root environment template
├── .gitignore
├── README.md
├── CONTRIBUTING.md            # Contribution guidelines
├── DEVELOPMENT.md             # Development setup guide
└── DATABASE_SCHEMA.md         # Database schema documentation

# Server
PORT=5000
NODE_ENV=development

# JWT
JWT_SECRET=your-secret-key-change-in-production
JWT_EXPIRES_IN=24h

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=roots_revealed_db
DB_USER=roots_revealed_user
DB_PASSWORD=your_password_here

# CORS
CORS_ORIGIN=http://localhost:3000

NEXT_PUBLIC_API_URL=http://localhost:5000
NEXT_PUBLIC_DEBUG=true

cd backend

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm test -- --coverage

cd frontend

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

The API includes comprehensive interactive documentation:

• Swagger UI: http://localhost:5000/api-docs
• OpenAPI Spec: http://localhost:5000/api-docs.json
• Postman Collection: backend/Roots-Revealed-API.postman_collection.json

http://localhost:5000/api

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login user
• POST /api/auth/logout - Logout user (requires auth)
• POST /api/auth/refresh - Refresh JWT token (requires auth)

• GET /api/charts - Get all charts (paginated, requires auth)
• POST /api/charts - Create new chart (requires auth)
• GET /api/charts/:id - Get specific chart (requires auth)
• PUT /api/charts/:id - Update chart (requires auth)
• DELETE /api/charts/:id - Delete chart (requires auth)

• POST /api/charts/calculate - Calculate birth chart (requires auth)
• GET /api/charts/:id/interpretation - Get BMAD & Symbolon interpretation (requires auth)

• GET /api/health - API health status
• GET / - API information

For detailed request/response examples and schemas, visit the Swagger UI when the server is running.

# Register
curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123","name":"John Doe"}'

# Login
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123"}'

curl -X POST http://localhost:5000/api/charts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Birth Chart",
    "birthDate": "1990-01-15",
    "birthTime": "14:30",
    "latitude": 40.7128,
    "longitude": -74.0060
  }'

curl -X POST http://localhost:5000/api/charts/calculate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1990-01-15",
    "birthTime": "14:30",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "houseSystem": "Placidus"
  }'

1. Open Postman
2. Click "Import" button
3. Select backend/Roots-Revealed-API.postman_collection.json
4. The collection includes all endpoints with example requests
5. Set the baseUrl variable to your server URL
6. Authenticate using Register/Login to auto-populate authToken

Protected endpoints require a JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Tokens are obtained from /api/auth/register or /api/auth/login responses and can be refreshed using /api/auth/refresh.

List endpoints support pagination via query parameters:

GET /api/charts?page=1&limit=10

Response includes pagination metadata:

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3
  }
}

All endpoints return consistent error responses:

{
  "success": false,
  "error": {
    "message": "Error description",
    "statusCode": 400
  }
}

Common status codes:

• 200 - Success
• 201 - Created
• 400 - Bad Request (validation error)
• 401 - Unauthorized (missing/invalid token)
• 404 - Not Found
• 500 - Internal Server Error

# Lint backend
cd backend && npm run lint

# Lint frontend
cd frontend && npm run lint

# Format code
npm run format

cd backend
npm run build
npm start

cd frontend
npm run build
npm start

1. Verify PostgreSQL is running:

pg_isready

2. Check database exists:

psql -U roots_revealed_user -d roots_revealed_db

3. Verify credentials in .env file

# Kill process on port 5000 (backend)
lsof -ti:5000 | xargs kill -9

# Kill process on port 3000 (frontend)
lsof -ti:3000 | xargs kill -9

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

• CONTRIBUTING.md - Git workflow and contribution guidelines
• DEVELOPMENT.md - Detailed development setup
• DATABASE_SCHEMA.md - Database design and schema

• COLOR_PALETTE_AND_DESIGN_SYSTEM.md - Comprehensive design system, color palette, typography, and component patterns
• ACCESSIBILITY_TESTING_GUIDE.md - WCAG 2.1 compliance and accessibility testing guidelines
• Quick Reference Guide - Quick reference for developers

• Project setup with Next.js and Express
• TypeScript configuration
• JWT authentication
• PostgreSQL integration ready
• Testing frameworks
• Code quality tools (ESLint, Prettier)

• User profile management
• Chart calculation engine
• Real database integration
• Chart storage and retrieval
• API rate limiting

• Chart visualization
• Aspect calculations
• Transit calculations
• Synastry analysis
• PDF chart reports

• Deployment configuration
• CI/CD pipeline
• Performance optimization
• Security hardening
• Monitoring and logging

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

ISC License

• Product Management Team
• Development Team

For issues and questions:

• Create an issue on GitHub
• Contact the development team

Last Updated: October 28, 2025
Version: 1.0.0
Status: Development