Tamil Panchangam Astrology Engine
A full-stack Tamil Panchangam application providing birth-chart calculations, daily Panchangam (Tithi, Vara, Nakshatra, Yoga, Karana), Dasha timelines, AI-powered interpretations, and PDF report generation.
Stack
| Layer | Technology |
|---|
| Frontend | React 18 + TypeScript + Tailwind CSS + shadcn/ui |
| Build | Vite 7 |
| Express layer | Node.js 20 + Express + Drizzle ORM (PostgreSQL) |
| Astrology engine | Python 3.11 + FastAPI + DuckDB |
| Ephemeris | pyswisseph (Swiss Ephemeris) |
| PDF generation | ReportLab + svgwrite |
| AI interpretation | OpenAI API |
Prerequisites
- Node.js 20+ and npm
- Python 3.11+
- PostgreSQL 16+ (for the Express/Drizzle layer)
- System libraries for PDF rendering (see below)
System libraries (macOS)
brew install cairo pkg-config freetype harfbuzz glib pango gdk-pixbuf ghostscript
System libraries (Ubuntu/Debian)
sudo apt-get install -y libcairo2-dev pkg-config libfreetype6-dev \
libharfbuzz-dev libglib2.0-dev libpango1.0-dev libgdk-pixbuf2.0-dev ghostscript
Setup
1. Clone and configure environment
git clone <repo-url>
cd tamil-panchangam
cp .env.example .env
# Edit .env and fill in OPENAI_API_KEY and DATABASE_URL
2. Install Node dependencies
npm install
3. Install Python dependencies
cd tamil_panchangam_engine
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .
cd ..
4. Set up PostgreSQL database (Express layer)
# Ensure DATABASE_URL is set in .env, then:
npm run db:push
5. Run in development
# Terminal 1 — Python FastAPI backend (port 8000)
cd tamil_panchangam_engine
source .venv/bin/activate
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
# Terminal 2 — Vite frontend dev server (port 5000, proxies /api → 8000)
npm run dev
Or use the convenience script (runs both):
bash scripts/start-dev.sh
6. Build for production
npm run build
# Outputs to dist/public/ — FastAPI serves this automatically
Environment Variables
See .env.example for the full list. Key variables:
| Variable | Required | Description |
|---|
OPENAI_API_KEY | For AI features | OpenAI API key |
DATABASE_URL | For Express layer | PostgreSQL connection string |
STATIC_DIR | No | Override path to built React app (default: dist/public) |
PORT | No | Express server port (default: 5001) |
Project Structure
tamil-panchangam/
├── client/ # React frontend (Vite)
│ └── src/
│ ├── components/ # UI components (shadcn/ui)
│ ├── pages/ # Route pages
│ └── lib/ # API client, query helpers
├── server/ # Express.js layer (Node)
│ ├── index.ts # Entry point
│ └── routes.ts # API routes
├── shared/ # Shared Zod/Drizzle schemas
├── tamil_panchangam_engine/ # Python FastAPI engine
│ ├── app/
│ │ ├── main.py # FastAPI entry point
│ │ ├── api/ # Route handlers
│ │ ├── engines/ # Core astrology calculation engines
│ │ ├── llm/ # OpenAI integration
│ │ ├── db/ # DuckDB connection + bootstrap
│ │ ├── pdf/ # PDF report generation
│ │ ├── repositories/ # Data access layer
│ │ ├── services/ # Business logic
│ │ └── schemas/ # Pydantic models
│ └── data/
│ └── panchangam.duckdb # Main database (NOT in git — see below)
├── scripts/
│ └── start-dev.sh # Dev startup convenience script
├── .env.example # Environment variable template
├── pyproject.toml # Python dependencies
├── package.json # Node dependencies
└── vite.config.ts # Vite build config
Database
The app uses DuckDB (tamil_panchangam_engine/data/panchangam.duckdb) as its primary store. This file is excluded from git due to its size (300+ MB). Options for sharing it:
- Git LFS:
git lfs track "*.duckdb"
- Cloud storage: Upload to S3/GCS and download during CI/CD setup
- Seed script: Regenerate from source data (if a seed script is available)
The legacy SQLite file (panchangam.db) is deprecated and can be ignored.
Deployment (Vercel — frontend only)
The React frontend can be deployed to Vercel as a static site. The Python engine must be hosted separately (e.g., Railway, Render, Fly.io).
# Build the frontend
npm run build
# Deploy with Vercel CLI
vercel --prod
Set VITE_API_URL (or configure the Vite proxy target) to point at your deployed FastAPI backend.
Domain Glossary
| Term | Meaning |
|---|
| Tithi | Lunar day (30 per lunar month) |
| Vara | Day of the week (with planetary ruler) |
| Nakshatra | Lunar mansion (27 total) |
| Yoga | Combined Sun+Moon longitude value |
| Karana | Half of a Tithi |
| Rahu Kalam | Inauspicious time period of the day |
| Yamagandam | Another inauspicious daily time window |
| Dasha | Planetary period system (Vimshottari) |
| Gochara | Current planetary transits over natal chart |
| Ashtakavarga | Eight-source point system for transit strength |
