# anhadlamba30/librejyotish architecture

> Architecture diagram of the GitHub repository anhadlamba30/librejyotish, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anhadlamba30/librejyotish
- Repository: https://github.com/anhadlamba30/librejyotish

## Overview

LibreJyotish is a stateless Vedic-astrology MCP server: a client supplies a tool request and receives structured calculations with conventions and warnings. Its domain stages include birth-chart and divisional-chart calculation, timing and transit analysis, panchang, and specialized strength, aspect, Jaimini, eclipse, and Saturn-period results; offline geocoding supports location input. The server dispatches requests to calculation modules, which share Swiss Ephemeris primitives and bundled data. Edges reflect README documentation and SOURCE INDEX references; unsampled server wiring is not inferred beyond those references.

Main entry points: [`librejyotish/server.py`](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/server.py) (Tool server), [`librejyotish/core/ephemeris.py`](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/ephemeris.py) (Ephemeris engine), [`librejyotish/core/constants.py`](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/constants.py) (Astrology constants), [`librejyotish/core/charts.py`](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/charts.py) (Natal and divisional charts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP interface"]
  node_server["Tool server<br/>[server.py]"]
  node_batch["Batch runner<br/>[server.py]"]
end

subgraph group_astro["Chart calculations"]
  node_charts["Natal and divisional charts<br/>[charts.py]"]
  node_drishti["Graha aspects<br/>[drishti.py]"]
  node_ashtakavarga["Ashtakavarga<br/>[ashtakavarga.py]"]
  node_shadbala["Shadbala<br/>[shadbala.py]"]
  node_jaimini["Jaimini padas<br/>[jaimini.py]"]
end

subgraph group_timing["Timing and almanac"]
  node_dasha["Vimshottari dasha<br/>[dasha.py]"]
  node_panchang["Panchang<br/>[panchang.py]"]
  node_transits["Current transits<br/>[server.py]"]
  node_eclipses["Eclipses<br/>[eclipses.py]"]
  node_saturn["Saturn periods<br/>[saturn_periods.py]"]
end

subgraph group_foundation["Shared foundations"]
  node_geocode["Offline geocoder<br/>[geocode.py]"]
  node_ephemeris["Ephemeris engine<br/>[ephemeris.py]"]
  node_ephedata[("Bundled ephemeris")]
  node_gazetteer[("City gazetteer<br/>[cities.csv]")]
  node_constants["Astrology constants<br/>[constants.py]"]
end

node_client(("MCP client"))

node_client -->|"requests tools"| node_server
node_server -->|"dispatches chart tools"| node_charts
node_server -->|"dispatches dasha"| node_dasha
node_server -->|"dispatches panchang"| node_panchang
node_server -->|"dispatches analysis"| node_ashtakavarga
node_server -->|"dispatches analysis"| node_shadbala
node_server -->|"dispatches padas"| node_jaimini
node_server -->|"dispatches eclipse queries"| node_eclipses
node_server -->|"dispatches period queries"| node_saturn
node_server -->|"dispatches lookup"| node_geocode
node_server -->|"serves transit tool"| node_transits
node_server -->|"runs batch operations"| node_batch
node_batch -->|"calls selected tool"| node_server
node_charts -->|"calculates positions"| node_ephemeris
node_charts -->|"uses aspects"| node_drishti
node_dasha -->|"reads birth positions"| node_ephemeris
node_panchang -->|"computes sky positions"| node_ephemeris
node_ashtakavarga -->|"reads positions"| node_ephemeris
node_jaimini -->|"uses chart results"| node_charts
node_jaimini -->|"uses positions"| node_ephemeris
node_saturn -->|"gets natal Moon"| node_charts
node_saturn -->|"scans Saturn"| node_ephemeris
node_shadbala -->|"uses chart data"| node_charts
node_shadbala -->|"uses sky positions"| node_ephemeris
node_eclipses -->|"calculates events"| node_ephemeris
node_ephemeris -->|"reads files"| node_ephedata
node_geocode -->|"searches cities"| node_gazetteer
node_ephemeris -->|"uses shared values"| node_constants
node_charts -->|"uses shared values"| node_constants
node_dasha -->|"uses shared values"| node_constants
node_panchang -->|"uses shared values"| node_constants
node_ashtakavarga -->|"uses shared values"| node_constants
node_jaimini -->|"uses shared values"| node_constants
node_saturn -->|"uses shared values"| node_constants
node_shadbala -->|"uses shared values"| node_constants

click node_server "https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/server.py"
click node_batch "https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/server.py"
click node_charts "https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/charts.py"
click node_drishti "https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/drishti.py"
click node_ashtakavarga "https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/ashtakavarga.py"
click node_shadbala "https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/shadbala.py"
click node_jaimini "https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/jaimini.py"
click node_dasha "https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/dasha.py"
click node_panchang "https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/panchang.py"
click node_transits "https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/server.py"
click node_eclipses "https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/eclipses.py"
click node_saturn "https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/saturn_periods.py"
click node_geocode "https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/geocode.py"
click node_ephemeris "https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/ephemeris.py"
click node_ephedata "https://github.com/anhadlamba30/librejyotish/tree/master/librejyotish/data/ephe"
click node_gazetteer "https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/data/gazetteer/cities.csv"
click node_constants "https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/constants.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_batch,node_client toneBlue
class node_charts,node_drishti,node_ashtakavarga,node_shadbala,node_jaimini toneAmber
class node_dasha,node_panchang,node_transits,node_eclipses,node_saturn toneMint
class node_geocode,node_ephemeris,node_ephedata,node_gazetteer,node_constants toneRose
```

## Components

### MCP interface

- [Tool server](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/server.py): `librejyotish/server.py`
- [Batch runner](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/server.py): `librejyotish/server.py`

### Chart calculations

- [Natal and divisional charts](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/charts.py): `librejyotish/core/charts.py`
- [Graha aspects](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/drishti.py): `librejyotish/core/drishti.py`
- [Ashtakavarga](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/ashtakavarga.py): `librejyotish/core/ashtakavarga.py`
- [Shadbala](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/shadbala.py): `librejyotish/core/shadbala.py`
- [Jaimini padas](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/jaimini.py): `librejyotish/core/jaimini.py`

### Timing and almanac

- [Vimshottari dasha](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/dasha.py): `librejyotish/core/dasha.py`
- [Panchang](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/panchang.py): `librejyotish/core/panchang.py`
- [Current transits](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/server.py): `librejyotish/server.py`
- [Eclipses](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/eclipses.py): `librejyotish/core/eclipses.py`
- [Saturn periods](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/saturn_periods.py): `librejyotish/core/saturn_periods.py`

### Shared foundations

- [Offline geocoder](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/geocode.py): `librejyotish/core/geocode.py`
- [Ephemeris engine](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/ephemeris.py): `librejyotish/core/ephemeris.py`
- [Bundled ephemeris](https://github.com/anhadlamba30/librejyotish/tree/master/librejyotish/data/ephe): `librejyotish/data/ephe`
- [City gazetteer](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/data/gazetteer/cities.csv): `librejyotish/data/gazetteer/cities.csv`
- [Astrology constants](https://github.com/anhadlamba30/librejyotish/blob/master/librejyotish/core/constants.py): `librejyotish/core/constants.py`

### Other components

- **MCP client**

## Connections

- MCP client → Tool server: requests tools (evidence: `README.md`)
- Tool server → Natal and divisional charts: dispatches chart tools (evidence: `librejyotish/server.py`)
- Tool server → Vimshottari dasha: dispatches dasha (evidence: `librejyotish/server.py`)
- Tool server → Panchang: dispatches panchang (evidence: `librejyotish/server.py`)
- Tool server → Ashtakavarga: dispatches analysis (evidence: `librejyotish/server.py`)
- Tool server → Shadbala: dispatches analysis (evidence: `librejyotish/server.py`)
- Tool server → Jaimini padas: dispatches padas (evidence: `librejyotish/server.py`)
- Tool server → Eclipses: dispatches eclipse queries (evidence: `librejyotish/server.py`)
- Tool server → Saturn periods: dispatches period queries (evidence: `librejyotish/server.py`)
- Tool server → Offline geocoder: dispatches lookup (evidence: `librejyotish/server.py`)
- Tool server → Current transits: serves transit tool (evidence: `README.md`)
- Tool server → Batch runner: runs batch operations (evidence: `librejyotish/server.py`)
- Batch runner → Tool server: calls selected tool (evidence: `librejyotish/server.py`)
- Natal and divisional charts → Ephemeris engine: calculates positions (evidence: `librejyotish/core/charts.py`)
- Natal and divisional charts → Graha aspects: uses aspects (evidence: `librejyotish/core/charts.py`)
- Vimshottari dasha → Ephemeris engine: reads birth positions (evidence: `librejyotish/core/dasha.py`)
- Panchang → Ephemeris engine: computes sky positions (evidence: `librejyotish/core/panchang.py`)
- Ashtakavarga → Ephemeris engine: reads positions (evidence: `librejyotish/core/ashtakavarga.py`)
- Jaimini padas → Natal and divisional charts: uses chart results (evidence: `librejyotish/core/jaimini.py`)
- Jaimini padas → Ephemeris engine: uses positions (evidence: `librejyotish/core/jaimini.py`)
- Saturn periods → Natal and divisional charts: gets natal Moon (evidence: `librejyotish/core/saturn_periods.py`)
- Saturn periods → Ephemeris engine: scans Saturn (evidence: `librejyotish/core/saturn_periods.py`)
- Shadbala → Natal and divisional charts: uses chart data (evidence: `librejyotish/core/shadbala.py`)
- Shadbala → Ephemeris engine: uses sky positions (evidence: `librejyotish/core/shadbala.py`)
- Eclipses → Ephemeris engine: calculates events (evidence: `librejyotish/core/eclipses.py`)
- Ephemeris engine → Bundled ephemeris: reads files (evidence: `README.md`)
- Offline geocoder → City gazetteer: searches cities (evidence: `README.md`)
- Ephemeris engine → Astrology constants: uses shared values (evidence: `librejyotish/core/ephemeris.py`)
- Natal and divisional charts → Astrology constants: uses shared values (evidence: `librejyotish/core/charts.py`)
- Vimshottari dasha → Astrology constants: uses shared values (evidence: `librejyotish/core/dasha.py`)
- Panchang → Astrology constants: uses shared values (evidence: `librejyotish/core/panchang.py`)
- Ashtakavarga → Astrology constants: uses shared values (evidence: `librejyotish/core/ashtakavarga.py`)
- Jaimini padas → Astrology constants: uses shared values (evidence: `librejyotish/core/jaimini.py`)
- Saturn periods → Astrology constants: uses shared values (evidence: `librejyotish/core/saturn_periods.py`)
- Shadbala → Astrology constants: uses shared values (evidence: `librejyotish/core/shadbala.py`)
