Panchang Engine — High-Level Design

Status: Draft for review · Part of: Astro Composer · Updated: 2026-10-24

The panchang engine turns one local day into five limbs — tithi (lunar day), vara (weekday), nakshatra (lunar mansion), yoga and karana (half-tithi) — each with exact start and end instants anchored to sunrise. It is pure arithmetic on binder positions and rise/set answers: no provider call, interpolation, timezone database or clock.

1. Purpose

Panchang is what users check against a printed almanac, so a convention error shows immediately. Four conventions matter:

• The day’s tithi is the one running at sunrise, not at midnight.
• Vara (the weekday) changes at sunrise.
• A tithi can be skipped (kshaya) or repeat (adhika).
• People expect an end time (“Panchami ends at 14:32”), not just a name.

The engine exists so that:

1. one sunrise definition anchors the day, tithi and vara;
2. every limb is an interval with exact boundary instants, not a sampled guess;
3. kshaya and adhika tithis are never deduplicated;
4. tithi and karana ignore ayanamsa while nakshatra and yoga inherit it;
5. every response names its profile, rulebook and binder provenance.

2. Where it sits

binder rise-set + positions ──┐
request · local date + offset ─┼──▶ panchang engine ──▶ five limbs + boundary instants
observer · profile · rulebook ┘

• Upstream: the composition facade supplies the local date, UTC offset, observer, profile and one rulebook handle; the binder client supplies sunrise, next sunrise and Sun/Moon positions on request.
• Downstream: the facade builds POST /v1/panchang; muhurta packs and calendar features reuse the same limb intervals.
• Never: it does not call a provider, interpolate an ephemeris, read a clock, use a timezone database, or produce festival and muhurta rules.

Input contract

Output contract

3. Responsibilities

Each area owns one decision and one deterministic rule.

4. Architecture

Diagram: reference design, not deployed behaviour.

The engine is a pure module with one seam: a boundary probe port. The engine picks the next instant it needs; the facade runs the binder read. That keeps the solver deterministic and testable without a network client, cache or clock.

5. Rules

1. Sunrise defines the day. Day tithi and vara are the ones at sunrise; midnight or noon boundaries are a different product and are not served.
2. Five limbs, two quantities. Tithi and karana use Sun–Moon elongation, nakshatra the sidereal Moon, yoga the sidereal Sun-plus-Moon sum, vara the sunrise instant. No other body participates.
3. The binder owns nakshatra. The engine reads its nakshatra id per probe and may use the in-segment remainder as a Newton step, never deriving an id from a longitude.
4. Tithi and karana ignore ayanamsa. Both are longitude differences, so a profile change cannot move them. Sidereal nakshatra and yoga do move; the response names the profile.
5. Boundaries are solved, not sampled. Every limb carries start and end instants; missing one second fails the request.
6. No ephemeris interpolation. The probe port returns longitude and speed and the engine only does arithmetic; the facade owns every binder read.
7. Half-open intervals. A limb beginning exactly at a boundary belongs to the new interval; one beginning at sunrise opens the day.
8. Kshaya and adhika are reported. A tithi with no sunrise inside is kshaya; one holding both the day’s sunrise and the next is adhika. Neither is removed, merged or renumbered.
9. Karana is a rulebook cycle. Seven movable names repeat eight times per lunation; the first half of Shukla Pratipada and the last three half-tithis are fixed. Names and positions come from the rulebook.
10. Vara is sunrise to sunrise. The id is the Sanskrit weekday (somavara) plus an index; display names belong to the client.
11. No timezone database, no clock. The caller supplies the local date and offset; the engine returns UTC instants and never resolves DST, reads the server clock or formats a date.
12. No partial panchang. Missing sunrise, missing next sunrise or a non-converged boundary fails the request; allowPartial does not cover the five limbs. A missing sunset is null.
13. The probe budget is a contract. Each boundary gets a bounded probe count; exhausting it is LIMIT_EXCEEDED, never an approximate boundary.
14. Deterministic order. Limbs are emitted tithi, vara, nakshatra, yoga, karana, intervals ordered by start. Two identical requests give byte-identical output.

6. Edge cases

Bad input fails loudly; nothing is silently approximated.

7. Out of scope

• Muhurta windows, Rahu kala, Yamaganda, Gulika, panchaka, Abhijit, hora and choghadiya (muhurta packs).
• Festival names, samvat, regional month names and calendar conversion.
• Sunrise, sunset and horizon astronomy (Astro Binder).
• Eclipses, upagraha, planetary war, transits and dasha periods.
• Alternative day boundaries at midnight or noon.
• Timezone database and DST resolution (caller and facade).
• Interpretation, remedies and almanac prose (product content).
• Caching and provenance storage (facade, result cache and provenance store).
• Matching, transits and natal chart assembly (chart core).

8. Planned code