naturalstupid/pyjhora

1. Overall shape

JHora is a Python package, not a single app: the core is an astrology computation engine, with a PyQt6 UI layered on top. The repository is organized around domain modules for panchanga, horoscope charts, dhasa systems, compatibility, prediction, and transit calculations.

2. Core computation boundary

The main computational boundary is jhora.panchanga.drik plus related panchanga modules. This layer computes time- and location-based astronomical values such as sunrise/sunset, tithi, nakshatra, yogam, karana, lunar months, special lagnas, planet positions, eclipse dates, and entry/transit events. Most higher-level horoscope features depend on these outputs.

3. Ephemeris and astronomical data

Planetary calculations depend on Swiss Ephemeris and the bundled ephemeris files under src/jhora/data/ephe. The README explicitly notes that accuracy is driven by the installed Swiss Ephemeris data. These files are a key external data dependency and are required for the core math to work.

4. Horoscope chart subsystem

jhora.horoscope.chart builds on the panchanga layer to produce chart-centric outputs: rāśi/divisional charts, bhava houses, arudhas, ashtakavarga, yogas, doshas, strengths, sphutas, and relationship/aspect tables. This is the central analysis layer for horoscope interpretation and is where most chart-derived data is assembled.

5. Dhasa engines

jhora.horoscope.dhasa is split into graha, raasi, annual, and sudharsana_chakra subpackages. Each module implements a specific dhasa-bhukti system and shares common inputs like planetary positions, nakshatra, divisional chart context, and configured year-duration rules. This subsystem is structurally separate from chart computation, but it consumes chart results heavily.

6. Transit, prediction, and compatibility

Three adjacent analysis subsystems sit on top of the core chart data:

- match for marriage compatibility tables and scoring,

- prediction for rule-based general/longevity-style interpretations,

- transit for tajaka, sahams, and annual/monthly/60-hour transit analysis.

These are downstream consumers of the same horoscope state, but each has its own domain rules.

7. Place and calendar data

Location lookup is handled by place_db.py and data files such as CSV/SQLite/DB place databases in src/jhora/data. The README notes support for multiple engines: CSV, pickle, and SQLite. Location data feeds latitude/longitude/time zone/elevation into panchanga and chart computations, so place resolution is a first-class dependency, not just UI input.

8. Configuration and constants

config.py, const.py, and _package_info.py define package-wide modes and defaults such as ayanamsa behavior, node handling, chart options, and feature flags. This is an important boundary because many algorithms are parameterized by global configuration rather than hardcoded behavior.

9. UI layer

jhora.ui contains multiple independent PyQt widgets rather than a single monolithic interface. The main surfaces are horo_chart_tabs.py for the full multi-tab experience, panchangam.py for one-page panchanga, vedic_calendar.py, match_ui.py, vedic_clock.py, vratha_finder.py, and chart-style dialogs. These widgets are presentation-only clients of the computation layer.

10. Internationalization and resource files

The lang directory holds multilingual strings and message catalogs in English, Tamil, Telugu, Hindi, Kannada, and Malayalam. UI text and some output labels are driven from these resources, so language selection is a presentation concern that does not alter the underlying calculations.

11. Static reference datasets

The package ships multiple domain datasets: marriage compatibility tables, festival CSVs, pancha pakshi data, geonames place data, user/factory settings, and documentation exports. These files are part of runtime behavior, not just documentation, because many calculations and lookups are table-driven.

12. Testing and verification

src/jhora/tests contains a substantial test suite, including book-exercise baselines and regression outputs. The README calls out thousands of tests and special baseline JSON files. Architecturally, this is important because the project treats numerical correctness and compatibility with published astrology references as a primary quality gate.

13. Packaging and runtime model

The repo is packaged as a Python library with pyproject.toml, requirements.txt, and src/jhora/setup.py. At runtime, it is intended both for direct library use and for launching PyQt widgets. There is also an MCP server wrapper mentioned in the README, which positions the library as a backend computation engine for other tools.

14. Key dependency flow

The main data flow is: place/date/time input enters the UI or API, panchanga/drik computes astronomical state, chart modules derive horoscope structures, and then dhasa/prediction/match/transit modules interpret those structures. Output is rendered in UI tabs, dialogs, or exported reports/PDFs, with tests validating the same pipeline against reference examples.