Tamil Jathakam AI Platform

A production-grade Tamil Vedic Astrology (Jathakam) platform: deterministic astronomical calculation, dasha/transit/yoga/dosha rule engines, and an AI interpretation layer that explains — but never invents — the calculated chart.

See docs/ARCHITECTURE.md for the full pipeline, database schema, AI architecture, Tamil language design, and phased plan.

Status

Phase 1 complete: monorepo scaffold, NestJS backend with a health check, Next.js frontend shell, local Postgres+pgvector via Docker Compose.

Phase 2 complete: Prisma schema for all 15 tables (backend/prisma/schema.prisma), initial migration applied and verified against a live Postgres instance, Prisma wired into the NestJS app (PrismaModule/PrismaService), integration test covering the full user → profile → jathakam → planet relation chain.

Phase 3 complete: birth-data intake. GET /locations/search (OpenStreetMap Nominatim, no API key) and GET /locations/timezone (offline tz-lookup + luxon, historically DST-aware) resolve a searched place to lat/lng/timezone; POST /profiles persists a validated birth profile + location (manual lat/lng/timezone correction supported). Frontend: a 3-step intake wizard at /new (birth details → birth place search → calculation settings), fully bilingual (தமிழ்/English toggle), wired to a "புதிய ஜாதகம் உருவாக்கு" button on the dashboard. Verified end-to-end in-browser against live Nominatim data and the local Postgres.

Phase 4 complete: astronomical calculation engine (backend/src/calculation/), built on sweph (Swiss Ephemeris bindings, Moshier mode — no ephemeris data files needed). CalculationService.computeChart() takes birth date/time/ timezone/lat/lng and returns Lagna + all 9 grahas with sidereal longitude, sign, degree, nakshatra, pada, whole-sign house, retrograde, combustion, classical dignity (exaltation/debilitation/own/friendly/enemy/neutral, with sources cited per graha), and a documented simplified strength score. Purely deterministic — no AI, no DB writes. POST /calculation/preview exposes it for debugging (spec §36). 31/31 tests pass, including integration tests validated against Makara Sankranti (a verifiable real-world fact) and a determinism check. Caught and fixed a real bug during testing: the engine wasn't converting local birth time to UTC before computing the Julian Day (it silently used local wall-clock digits as if they were UTC) — a test asserting different timezones must yield different results caught it.

Phase 5 complete: jathakam engine (backend/src/jathakam/) — persists a birth profile's calculated chart. POST /jathakams {profileId} loads the profile+location, calls CalculationService, and writes Jathakam + Planet (Lagna + 9 grahas) + House (12 whole-sign bhavas with lord, lordHouse, occupants) rows; GET /jathakams/:id and GET /jathakams/profile/:profileId read them back. Responses are enriched with Tamil/English sign and nakshatra names (jathakam/names.ts) so Lagna/Rasi/Nakshatra are actually readable, not just numeric indices. The /new wizard now calls this automatically after saving a profile and shows the result (லக்னம், ராசி, நட்சத்திரம் + பாதம்), with the birth-time-accuracy warning surfaced again here since Lagna is time-sensitive. 37/37 tests pass. Caught and fixed a test-isolation bug: every e2e spec shared one dev-local user and each deleted it in afterAll, so when Jest ran spec files concurrently one file's cleanup cascade-deleted another file's still-in-use birth profile, intermittently breaking jathakam.e2e-spec.ts with a foreign-key violation; fixed by having each spec delete only the rows it created.

Phase 6 complete: South Indian style Rasi chart renderer (frontend/src/components/chart/SouthIndianChart.tsx) — an SVG component using the traditional fixed 4x4 grid layout (Aries fixed at top row, signs proceed clockwise, center 2x2 merged into one open area). Shows, per cell: the Tamil/English sign name, the house number relative to Lagna, a diagonal marker on the Lagna cell, and each occupying graha's abbreviation — colored red and marked when combust, suffixed "(வ)"/"(R)" when retrograde. Backend: House rows in JathakamSummary now also carry signName (small addition to jathakam.service.ts, same enrichment pattern as planets). Wired into the /new wizard results screen, verified live in the browser in both Tamil and English against the raw API response, cell-by-cell. 37/37 backend tests still pass (no backend logic changed beyond the one-field enrichment).

Phase 7 complete: Navamsa (D9) chart (backend/src/jathakam/divisional-charts.ts). The classical per-modality navamsa rule (movable signs count from themselves, fixed signs from the 9th sign, dual signs from the 5th) is implemented as the standard unified formula (signIndex*9 + navamsaIndex) % 12, behind a small DivisionalChartCalculator interface so D2/D3/etc. can slot in later without restructuring. Persisted as a DivisionalChart row per jathakam; JathakamSummary.navamsa exposes it in the same shape as the D1 houses, so the existing SouthIndianChart component renders it with zero changes (centerLabel="நவாம்சம்"). Verified two ways: a hand-derived per-modality truth table for all 12 signs in the unit tests, and — before trusting the code — every graha's navamsa placement in a live API response was independently recomputed by hand and matched exactly; the rendered D9 chart in the browser was then checked cell-by-cell against that same response. 41/41 tests pass.

Also added (user request, kept for last): Phase 21 — Panchangam (daily almanac) — date+location-based tithi/vaara/nakshatra/yoga/karana, sunrise/sunset, and Rahu Kalam/Yamagandam/Gulika Kalam/Nalla Neram/ Durmuhurtham/Varjyam. Independent of the birth-chart pipeline (no profile needed, just a date + place); recorded in docs/ARCHITECTURE.md § Phased plan.

This is the beginning of the README. Read the rest at the original. Read the full README ↗