NAKSHATRAA

A full-stack Vedic astrology platform for structured Kundli generation, multilingual predictions, asynchronous report processing, and deployable application workflows.

Overview

NAKSHATRAA combines astronomical calculations, prediction workflows, PDF generation, email delivery, and a modern web interface in one application. The project is organized around a frontend, Flask API, background workers, and supporting infrastructure.

Key Features

• Kundli generation using Swiss Ephemeris-based calculations
• English and Marathi prediction workflows
• Rashi, Dasha, and transit-aware prediction processing
• Background PDF generation and email delivery
• Celery and Redis for asynchronous jobs
• Health checks, structured logging, and rate limiting
• Docker Compose for reproducible multi-service environments
• Responsive frontend focused on clear presentation of results

Technology Stack

Layer	Technologies
Backend	Flask, Celery, Redis, Swiss Ephemeris
Frontend	Vite, Zustand, component-based UI
Infrastructure	Docker Compose, background workers, health checks

Architecture

User
  │
  ▼
Frontend (Vite)
  │
  ▼
Flask API
  ├── Astronomical / prediction logic
  ├── PDF generation
  └── Email workflows
        │
        ▼
   Celery + Redis

Swiss Ephemeris ──► astronomical calculations
Docker Compose ──► local/deployment orchestration

The frontend handles user interaction and result presentation. The Flask backend coordinates application logic, while Celery and Redis handle work that does not need to block the request. Swiss Ephemeris provides the astronomical calculation layer.

Repository Structure

.
├── backend/             # Flask application, services, and Celery tasks
├── frontend/            # Vite application and UI components
├── workers/             # Background processing code, where separated
├── docker-compose.yml   # Multi-service orchestration
├── .env.example         # Environment variable template
└── README.md

The exact structure may expand as backend services and workers are separated further. Update this section whenever a major directory is added or moved.

Running the Project

NAKSHATRAA is designed to run as a multi-service application. The recommended local workflow is to use the repository's Docker Compose configuration when available.

docker compose up --build

For component-level development, follow the dependency and startup instructions in the relevant backend/ and frontend/ documentation.

Configuration: keep secrets and environment-specific values in local environment files or deployment secrets. Do not commit credentials to the repository.

Example Use Cases

• Generate personalized Kundli reports
• Produce multilingual astrology summaries
• Run report generation asynchronously
• Deliver generated reports through email workflows
• Use the project as a base for regional astrology products

Development Notes

The project is intended to demonstrate production-oriented full-stack engineering around a domain-specific workflow. Accuracy of astronomical calculations, reliability of asynchronous jobs, and clarity of user-facing explanations should be treated as core quality concerns.

Planned Documentation Improvements

Future documentation can include screenshots, a current architecture diagram, representative API requests/responses, a complete environment-variable reference, and a hosted demo link when those assets are available.

Project Positioning

NAKSHATRAA is a domain-specific astrology application rather than a simple static website. It demonstrates integration of calculation services, backend orchestration, asynchronous processing, multilingual UX, reporting, and deployment infrastructure.