astrology design library
Astrology6 MIN READ42 / 116

Vedic Engine — High-Level Design

Status: Proposed reference design · Updated: 2026-10-24 · Delivery form: reusable module

Implementation tasks: Vedic development plan, with HLD references, dependencies and acceptance criteria per task. The Vedic package specifications split the logical engine into independent libraries under packages/vedic/src/*, with public exports, source paths and direct requirements.

The Vedic engine consumes shared chart facts (Vedic astrology, Jyotish, uses the sidereal zodiac) and applies a named Vedic profile and versioned rulebook. It returns calculated results and the rules behind them for chart screens, timelines, matching and calendar features. It is a sibling of the Western engine.

Vedic engine high-level architecture Proposed reference design. Product callers use a Vedic engine coordinator with a versioned profile and rulebook. The coordinator invokes requested technique modules and shared Chart Composer, which accesses the two provider adapters through Astro Binder. Responses contain calculated factors and provenance. An upstream binder records which astronomy ports are available; rise/set, declination and mean longitude stay closed gates, naming their owning task, until the host connects them. Boxes represent module ownership rather than independently deployed services. Vedic Engine — High-Level Design Vedic techniques over shared chart facts; explicit profiles, rule evidence and capability gates. Product callersResolved contexts · selected techniques Vedic engine · proposed reusable module boundary Profiles and rulebooksAyanamsa · houses · node policyVarga / dasha / sunrise conventions Engine coordinatorCapability and layer selectionComposer reads · module assembly Evidence and resultsCalculated factors · rule identifiersVersions · contributing chart references Chart judgmentsDignity · combustion · yogasDoshas · named exceptions Varga calculationsDivisional charts and framesVersioned mapping schemes Dasha calculationsVimshottari period hierarchyPinned year and balance rules Strength calculationsStrength factors · ashtakavargaNamed tables and prerequisites PanchangSunrise-anchored limb intervalsSolved calendar boundaries Vedic transitsGochara · Sade SatiReference-chart evaluations MatchingAshtakoota · dosha checksScores and cancellations MuhurtaPurpose-specific election packsReuse panchang and chart rules Only selected families run; their own prerequisites determine execution order. context · profile · technique request resolve policy assemble calculated factors and evidence requested technique families Shared dependencies · same contracts for both traditions Shared Chart ComposerChart snapshots · bounded astronomy probesAssemble Binder facts under an explicit contextProposed smaller scope; no tradition rules Astro BinderSwiss adapter + NASA adapterProvider routing · canonical astronomy · base semanticsPreserve capabilities and contributing provenance chart / astronomy probe requests shared calls Vedic upstream binder · gatesOpen: positions · houses · probesClosed until connected: rise/set (B-01 → C-05)declination · mean longitude (new Binder reads) bind gates · connect only named ports capabilities · probe sessions future reads via host ports Synchronous calls / dependencies; values return to the caller. Solid outline: ownership boundary Reference design, not deployed behavior. Engine rules are versioned; provider access stays behind Composer and Binder. Hosts own civil-time resolution, saved charts and transport. Interpretation and rendering consume these calculated results.

This is the proposed split discussed after the original consolidated Composer design. The components are implemented as workspace libraries under packages/vedic/src/* (no deployed endpoint); reviewed tables and missing upstream astronomy remain gated as described below. Existing guides under chart-composer/ remain detailed references; their old placement does not mean the same rules should also run in the shared Composer.

Boundary and ownership

Product callers provide an absolute instant, observer where needed, requested layers, a profile, and any date window or chart pair. The host resolves civil timezones before calling the engine. The engine asks shared Chart Composer for the chart facts it needs. Composer assembles Binder positions, houses, angles, signs, nakshatras (the 27 lunar mansions), motion and shared aspect geometry into an immutable chart snapshot. Neither the engine nor Composer selects Swiss or NASA directly.

The Vedic engine owns chart judgment, varga (divisional chart) mappings, dasha (planetary period) arithmetic, strength tables, Vedic drishti rules, yoga/dosha detection, panchang conventions, matching scores and election rules. Binder owns numerical astronomy and shared base semantics. Angular aspects supplied by Binder are distinct from Vedic drishti rule relationships owned here. Interpretation wording and remedies belong to product content; birth records and saved results belong to application storage.

Component map

Component Responsibility Existing design reference
Engine coordinator Resolve a profile, validate requested layers, obtain facts, sequence dependencies and assemble one response Proposed assembly boundary
Profiles and rulebooks Pin ayanamsa (sidereal offset from the tropical zodiac), houses, node convention, varga schemes, dasha year length, sunrise definition and rule tables Convention register
Chart judgments Dignity, combustion, planetary war, yogas, doshas and named exceptions Chart core is a starting point; its neutral chart assembly stays with Composer
Varga calculations Divisional charts and their frames under explicit schemes Varga engine
Dasha calculations Vimshottari periods and nested UTC intervals; other systems require their own versioned definitions Dasha engine
Strength calculations Named strength systems and ashtakavarga tables; expose calculated factors rather than one unexplained score Strength specification (V-06); Shadbala totals stay gated
Panchang Sunrise-anchored limbs, boundary intervals and skipped/repeated tithis (lunar days) Panchang engine
Vedic transits Gochara (transits counted from the natal Moon), Sade Sati and reference-chart evaluations Transit engine
Matching Ashtakoota, dosha checks and rule-defined cancellations for a chart pair Matching engine
Muhurta Purpose-specific muhurta (election) filters over panchang, chart and time-window facts First pack yatra@1 (V-13); uses the same panchang and chart judgments
Evidence and result assembly Retain contributing chart/probe references, rule matches, unsupported layers and version identities Proposed response boundary

These are logical responsibilities within the Vedic domain. The package specifications give independent calculations their own workspace libraries and retain a small engine coordinator. The diagram’s family dependencies do not imply a deployment per box or execution of every family for each request. Muhurta consumes panchang and chart judgments; transit scoring can consume natal strength results. Detailed sequencing belongs in the individual operation designs.

Proposed interface

Operation Inputs Result
capabilities Profile and requested layer selection Supported layers, required upstream facts and rulebook identities
chart Chart context, profile and layers Vedic chart judgments, selected vargas, strengths and dasha periods
panchang Local date/day window, resolved timezone context, observer and profile Sunrise-to-sunrise limbs with boundary instants
transits Immutable reference chart, search window and transit policy Evaluated transit facts and solved intervals where supported
matching Two compatible chart snapshots and a matching policy Per-rule scores, doshas and cancellation evidence
muhurta Purpose, location, bounded window and election pack Accepted windows and the factors that accepted or excluded them

These names describe a module contract, not HTTP routes. Language and hosting remain open. Single-chart rules are pure functions of supplied facts and versions; the coordinator can perform asynchronous Composer reads when a request needs additional instants.

Shared Composer contract

The proposed chart snapshot contains the resolved instant, observer context, zodiac/ayanamsa, house convention, ordered body geometry, angles, shared facts and Binder provenance. Its identity must include those conventions and the contributing versions. Vedic-specific judgments are added by this engine and do not mutate the snapshot.

For calendar and window work, Composer also needs a bounded astronomy-probe port backed by Binder. The Vedic engine owns the definition of a tithi or muhurta boundary and its search policy; each astronomical evaluation comes through Composer. It must not interpolate provider positions or derive sunrise from an improvised horizon model.

Capability gates and failures

  • Natal, varga and Vimshottari work can start from the existing position and house contracts.
  • Panchang and sunrise-based muhurta require an explicit rise/set contract and horizon definition. That support is proposed in the existing Binder integration design and must be verified before enabling them.
  • Strength and advanced techniques need an input audit; unsupported astronomical quantities must be declared rather than inferred from absent fields.
  • One resolved rulebook and profile apply to a response. A changed calculation rule gets a new identity.
  • Upstream failures keep their error codes. Do not switch providers or silently change ayanamsa, houses, node convention or sunrise policy to complete a result.
  • Partial output is opt-in and must list missing layers; a missing required factor blocks its dependent layer.
  • Missing upstream astronomy (rise/set, declination, mean longitude) is declared as a port in @astrology/vedic and connected by the upstream binder. Until a host supplies the port, capabilities report the gate and its owning task; supplying it enables the dependent layers with no calculator change.

Responses retain profile, rulebook, engine and Composer versions, contributing Binder evidence, rule identifiers and input snapshot references. The host owns persistence and cache policy; cache identity must include all calculation conventions. Interpretation consumes this evidence later.

Assembly and delivery

First agree the smaller shared Composer contract, then extract chart judgments, varga and dasha responsibilities from the consolidated design into one Vedic engine. Reuse their existing rules and fixtures; do not maintain a second implementation under Composer. Add strengths, panchang, transits, matching and muhurta only after their definitions and upstream capability gates are met.

Verification should cover convention boundaries, deterministic replay of saved inputs, preserved provenance, layer dependency failures and reviewed reference fixtures. These are acceptance requirements for future implementation, not tests executed by this documentation change.