astrology design library
Astrology6 MIN READ48 / 116

Western Engine — High-Level Design

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

Implementation tasks: Western development plan, with HLD references, dependencies and acceptance criteria per task. The Western package specifications define independently importable libraries under packages/western/src/*, their public exports, source paths and direct requirements. The dependency adapters record how each Western package narrows its Compose/Binder contact to a Western-owned shape so techniques stay runnable before upstream packages are frozen. The technique conventions fix one named variant per advanced technique and name the variants that stay unsupported.

The Western engine consumes shared chart facts and applies an explicit Western technique profile and versioned rulebook. It returns natal judgments, relationship analyses and time-based technique results for applications and interpretation. It is a sibling of the Vedic engine.

Western engine high-level architecture Proposed reference design. Product callers use a Western 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. Boxes represent module ownership rather than independently deployed services. Western Engine — High-Level Design Western techniques over shared chart facts; explicit conventions, derived-point origins and event evidence. Product callersResolved contexts · selected techniques Western engine · proposed reusable module boundary Profiles and rulebooksZodiac · houses · aspects / orbsRulership and technique definitions Engine coordinatorCapability and layer selectionComposer reads · module assembly Evidence and resultsCalculated factors · rule identifiersVersions · contributing chart references Natal judgmentsRulership · dignity · emphasisElements · aspect patterns Transit analysisReference-chart contactsBounded event windows SynastryCross-chart contactsHouse overlays Composite chartsNamed relationship methodsLabel derived chart geometry ProgressionsTechnique-mapped instantsExplicit angle conventions ReturnsReference-longitude eventsBounded search · location policy DirectionsSelected solar-arc conventionDerived points and contacts HarmonicsProfile-defined transformationsDerived points and patterns 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 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 a proposed design, not an inventory of implemented engines or available endpoints. It uses the smaller shared Composer boundary described in the Astrology overview. The existing consolidated Composer design predates this split.

Boundary and ownership

Product callers supply resolved instants, observing locations, requested techniques, a profile and reference chart or chart pair where appropriate. Chart Composer assembles immutable chart facts through Binder. The Western engine never chooses an ephemeris adapter (the source of tabulated planetary positions) or applies an ayanamsa, the angular offset between the tropical and sidereal zodiacs, to a position that Binder already converted.

The engine owns Western chart judgments, relationship techniques, progression/direction conventions, return definitions and harmonic transformations. Binder owns provider calculations, coordinates, houses, motion and shared angular aspect geometry. Composer owns chart context and assembly. Interpretation text, chart drawing and durable user data belong to downstream products.

The tropical zodiac, which measures signs from the vernal equinox, is an initial profile choice, not the definition of all Western work. A sidereal profile (signs anchored to the fixed stars) must explicitly name an upstream-supported ayanamsa. House system, node convention (mean or true lunar node), aspect/orb policy (the tolerance around an exact aspect angle) and technique variants also need explicit versioned identities.

Component map

Component Responsibility Inputs and boundary
Engine coordinator Resolve a profile, check technique support, obtain facts and assemble one result Reference charts, requested layers and windows
Profiles and rulebooks Pin zodiac, houses, aspect policies, rulership schemes and technique conventions Immutable rule resources, not mutable per-request defaults
Natal judgments Elements/modalities, rulership and dignity assessments, house emphasis and aspect patterns Shared natal facts and Binder-calculated aspects
Transit analysis Compare moving chart facts to a reference chart and find bounded event windows Composer snapshots/probes; explicit event definitions
Synastry Cross-chart aspect relationships and house overlays Two context-tagged charts; shared geometry rules rather than copied aspect math
Composite charts Named relationship-chart construction methods Two reference charts; derived points identified separately from observed positions
Progressions Map a requested age/date into technique-specific chart contexts Named progression and progressed-angle conventions; Composer supplies astronomy
Returns Define and find a body’s return to a reference longitude, then request the event chart Bracketed search through Composer probes, an explicit location policy and tolerance
Directions Apply the chosen directional technique and report resulting contacts Start with an explicit solar-arc convention; primary directions are a separate future scope
Harmonics Transform a reference chart under an explicit harmonic policy Derived coordinates stay labelled as technique output rather than provider observations
Evidence and result assembly Retain charts/probes, rule matches, transformation definitions and version identities Explainable outputs for interpretation and visualization

The diagram groups techniques as module families within one engine, not as independently hosted services. These families are implemented as independent workspace packages composed by the engine. Its family dependencies show the coordinator’s access, not a mandatory execution order. Only requested techniques and their prerequisites run.

Proposed interface

Operation Inputs Result
capabilities Profile and technique selection Supported techniques, required facts and rulebook identities
natal Chart context, profile and selected judgments Natal factors and rule matches
transits Reference chart, bounded window and contact policy Transit contacts and event intervals where supported
synastry Two chart snapshots and relationship policy Cross-chart contacts and overlays
composite Two chart snapshots and named method Derived relationship chart with method evidence
progressions Reference context, target date and technique Progressed facts plus the mapped calculation contexts
returns Body, reference longitude, bounded window and location policy Solved event instant and corresponding chart
directions / harmonics Reference chart and named technique parameters Derived points and contact evidence

These are design-level module operations. This HLD does not require REST, a JVM service or a separate deployed process. Pure technique calculations sit behind a coordinator that may request additional Composer charts and astronomy probes.

Shared Composer contract

Both traditions use the same context-tagged chart snapshot: resolved instant, observer, zodiac, ayanamsa if selected, house convention, ordered body geometry, angles, shared facts and provenance. Different technique profiles may request different snapshots; sharing a contract does not mean sharing a sidereal and tropical result as if their longitudes were interchangeable.

For synastry, the shared geometry surface needs cross-chart aspect evaluation and placement against the target chart’s cusps (house boundaries). Reuse Binder’s base rules through Composer; the engine defines what those contacts mean. Single-chart aspect annotations alone are insufficient for this operation.

Time-dependent techniques use a bounded probe interface through Composer and Binder. The Western engine chooses the technique’s target condition and solver policy; Binder supplies the actual astronomy for each requested instant. Return searches must handle angle wrapping and distinguish multiple candidate events within the requested window. A location-dependent return chart requires an explicit birth/current/event location policy.

Capability gates and failures

  • Begin with natal judgments and selected transit evaluations over supported body/house facts.
  • Synastry needs shared cross-chart geometry exposed through the Composer contract. Composite construction needs an agreed named method; midpoint and time/place-derived methods cannot be conflated.
  • Progressions and directions stay disabled until their time, angle and convention definitions have reviewed fixtures. Primary directions need a separate input and coordinate review.
  • Return windows require bounded probes and solver limits. Bulk queries are an optimization; a capability must not depend on an unimplemented batch endpoint being assumed available.
  • Declination-based parallels, fixed stars, eclipse work and other extensions need extra Binder capabilities and are excluded from initial delivery.
  • Preserve upstream errors and explicitly report no-event, ambiguous-event or exhausted-search outcomes. Do not silently change house system, location, technique variant or provider.

Responses carry profile, technique/rulebook, engine and Composer versions; contributing charts and Binder provenance; derived-point origins; and rule identifiers. Partial output is opt-in and names missing layers. The host owns saved charts, privacy, transport and version-aware caching.

Assembly and delivery

Agree the shared Composer contract alongside the Vedic engine, then add Western natal judgments and transit analysis. Expose shared cross-chart geometry before synastry. Deliver composite, progressions, returns, directions and harmonics as separately gated capabilities with explicit conventions rather than treating the technique list as initial-release support.

Acceptance checks should cover independent reference charts, angular wrap, search boundaries, multiple/no-event results, location policy, deterministic replay and evidence retention. These describe future implementation verification, not tests executed by this documentation change.