A little clarity.
The whole system.

Astrology vocabulary, bottom up

The Sun can be in one sign and a different house. Two charts can give it different sign labels without moving it across the sky. A point called a “planet” may turn out to be…

Layer 0 — The sky and the clock

This layer defines the astronomy underneath every chart: how an instant is labelled, how a direction on the sky is described, and from which point the measurement is made. A…

Binder and architecture terms

This page defines the software vocabulary used by the Astro Binder, the part of the system that turns a request for "positions at this instant and place" into checked,…

Glossary A–Z

Use this page as a way back into the lessons. Each row gives a one-sentence definition and links to the section that explains the term in full, with the reasons and examples…

Layer 2 — Signs, houses and angles

This layer separates two twelve-part divisions that are easy to confuse. Signs divide the zodiac and depend only on a body's longitude. Houses divide the local sky of one…

Layer 1 — The zodiac and the ayanamsa

This layer defines the circle that astrology uses to name positions, and the two ways of choosing where that circle starts. Two charts can put the same Sun in different signs…

Layer 6 — The Vedic stack

This layer defines the vocabulary of Jyotish, the Indian astrological tradition. Each entry opens with a definition, explains why the concept exists, works one example with…

Layer 3 — Bodies

This layer defines the objects whose positions a chart records. Not every chart symbol stands for a physical planet: the Sun is a star, the Moon is a satellite, and a lunar…

Layer 4 — Aspects

This layer defines the relationships a chart draws between two positions. Two planets can occupy different signs and still be related by a recognised angle. The terms below…

Layer 5 — Charts and time techniques

This layer defines the kinds of chart an astrologer can build and the techniques used to time events from them. Each entry opens with a definition, explains why the technique…

Sources and how to read them

A short explanation can make a new idea approachable. When you want to go further, the source should match the question: a coordinate reference explains geometry, a…

Layer 7 — Delivery and rendering

This layer names the ways calculated chart data reaches a reader: drawings, tables, animations, programmatic interfaces and files. None of these views changes the sky used in…

Data examples

The lessons explain the ideas; these sketches explore how to carry them in data. Read a record as a set of related facts, then connect its fields back to the sky, chart or…

Ephemeris

Designs for the astronomy layer behind every astrology calculation. An ephemeris is a table or engine that gives the positions of the Sun, Moon and planets at chosen…

Astro Binder — Package Architecture

Astro Binder is the astronomy assembly inside @astrology/ephemeris. Routing, normalization and Swiss/NASA providers are internal modules. Applications normally use…

Swiss Ephemeris adapter — workspace module

The Swiss Ephemeris adapter translates the Swiss engine into the shared contract. The reusable @astrology/ephemeris package implements the standalone…

Swiss adapter module implementation

The implemented slice uses the astronomy contract package and the internal Swiss module of ephemeris: adapter-contract and swiss-ephemeris-adapter. The former HTTP host,…

NASA Adapter — High-Level Design

The NASA adapter is the only component that knows JPL Horizons. It builds a query, guards the call, verifies the response signature, parses the text table into typed values…

NASA adapter module design

This is the module-level design of the @astrology/ephemeris workspace package. It maps the HLD onto the @astrology/astronomy-contracts, the same way the Swiss implementation…

Provider Router — High-Level Design

The router turns a canonical request into exactly one provider decision: a provider, a reason and a cache key, or a typed error when nothing can serve. It holds no results…

Canonical Normalizer — High-Level Design

The normalizer converts one provider answer into the canonical contract: canonical identifiers, units and frame, exactly one zodiac conversion, one rounding point and a…

Astrology Semantics — High-Level Design

The module turns canonical astronomy into signs (twelve 30° divisions of the zodiac), nakshatras (27 lunar mansions), padas (nakshatra quarters), motion, aspects and houses.…

Drift Validator — High-Level Design

Drift is a growing disagreement between the primary engine and an independent reference. The drift validator recomputes sampled cases with Swiss Ephemeris and JPL Horizons,…

Calculation Facade — High-Level Design

The facade is the single entry point for every calculation: cache, one provider, normalisation, enrichment and provenance. It computes no astronomy and no astrology.

Result Cache — High-Level Design

The cache stores normalised provider results for an exact request, with the provenance that produced them. A hit returns the same canonical values without a provider call.

Provenance Store — High-Level Design

Provenance is the evidence of how a value was produced. Each response yields one immutable audit record: the provider, engine version, ephemeris files, flags and precision…

Astrology

Designs for the chart layer above the ephemeris: how canonical positions become natal charts, divisional charts (vargas), dashas (planetary period timelines), panchang (the…

Package structure and application integration

The workspace has eight reusable packages and one validation tool. A package represents a domain boundary or an application assembly boundary. Calculators, profiles,…

Astrology development plan

The current package structure is authoritative. Eight reusable workspace packages cover astronomy contracts, astrology primitives, Ephemeris, Composer, Vedic, Western,…

Composer module specifications

The current package structure defines the workspace boundaries. The modules below share their owning domain's package manifest and build. Their factories and helper exports…

Chart Composer tasks

Modules share the Composer domain package. Read the module specifications and current package boundaries for source ownership and public APIs. See the overall assignment and…

Astro Composer — High-Level Design

Implementation tasks: Composer development plan, with HLD references, dependencies and acceptance criteria. The Compose package specifications define the independent shared…

Panchang Engine — High-Level Design

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…

Transit Engine — High-Level Design

The transit engine compares a moving sky against an immutable reference chart: gochara (transit) positions from the natal Moon, Sade Sati phases and ashtakavarga scores,…

Matching Engine — High-Level Design

The matching engine evaluates ashtakoota (eight-factor compatibility) for two charts: eight kootas, thirty-six points, the doshas (faults) they imply and the cancellation…

Chart Core — High-Level Design

Chart core turns one binder snapshot plus one profile into the D1 chart: frame, houses, bodies and planet judgements. It is the only engine that picks the chart frame, and…

Varga Engine — High-Level Design

The varga engine maps one sidereal D1 (natal chart) longitude into each of the sixteen Shodasavarga signs, then builds the varga frame from the same mapping. It is pure…

Dasha Engine — High-Level Design

The dasha engine turns the Moon's position at birth into a Vimshottari timeline: mahadasha, antardasha and pratyantardasha (first-, second- and third-level planetary periods)…

Astro Composer — Research and Convention Register

Current capability/precision corrections are recorded in the HLD alignment review. Figures and older endpoint proposals remain historical references; they do not override the…

Vedic module specifications

The current package structure defines the workspace boundaries. The modules below share their owning domain's package manifest and build. Their factories and helper exports…

Vedic engine tasks

Modules share the Vedic domain package. Read the module specifications and current package boundaries for source ownership and public APIs. Authority: Vedic HLD; detailed…

Vedic Engine — High-Level Design

Implementation tasks: Vedic development plan, with HLD references, dependencies and acceptance criteria per task. The Vedic package specifications split the logical engine…

Vedic Strength Systems — Specification (V-06)

This document defines the strength systems the Vedic engine may later calculate, the inputs each factor needs, and which of those inputs Composer can already supply. It is…

Muhurta Pack `yatra@1` — Specification (V-13)

A muhurta is an auspicious time window chosen for a purpose. The first muhurta purpose pack selects daytime windows for starting a journey (yatra). It is a pure filter over…

Yoga/Dosha Pack `parashari-core@1` — Specification (V-12)

The first named pack of yogas (named planetary combinations) and doshas (named afflictions). It deliberately holds three rules, each written in the evaluator's existing…

Western module specifications

The current package structure defines the workspace boundaries. The modules below share their owning domain's package manifest and build. Their factories and helper exports…

Western engine tasks

Modules share the Western domain package. Read the module specifications and current package boundaries for source ownership and public APIs. Authority: Western HLD. See…

Western Engine — High-Level Design

Implementation tasks: Western development plan, with HLD references, dependencies and acceptance criteria per task. The Western package specifications define independently…

Western dependency adapters

The Western packages are built ahead of a frozen Compose implementation by narrowing every upstream contact to a Western-owned shape. An adapter copies values into that…

Western technique conventions (W-05)

W-06–W-10 each implement one named convention. This directory fixes exactly one variant per technique, names the variants that stay unsupported, and lists the Composer facts…

Composite Method `midpoint@1` — Specification (W-05)

A composite chart is a relationship chart: one derived chart built from two admitted reference charts. Two construction families exist and are not interchangeable:

Secondary Progressions `secondary-day-for-year@1` — Specification (W-05)

A progression maps a target date to a calculation instant, then asks Composer for real astronomy at that instant. Nothing is extrapolated from the birth chart: the progressed…

Solar Return `solar@1` — Specification (W-05)

A return is the instant a body reaches a target ecliptic longitude again, followed by the chart for that instant. Two separate jobs live here: a bounded root search through…

Solar-Arc Directions `solar-arc-naibod@1` — Specification (W-05)

Solar-arc directions move every point of a reference chart by one shared arc and compare the moved points with the original chart. The technique is a static transformation…

Harmonic Chart `harmonic-n@1` — Specification (W-05)

A harmonic chart multiplies every ecliptic longitude by an integer factor. It is the smallest transformation in the engine and the easiest one to mislabel: the output is…

HLD alignment and correction review

The HLDs support shared chart assembly above Binder and separate Vedic/Western calculation ownership. Every planned calculation family maps to an existing component or…

Research

Market and domain research behind the ephemeris and astrology designs. Neither document describes shipped behaviour; both inform product and vocabulary decisions.

Astrology App Competitor Analysis Research

1. report.md — Market bifurcation, three paths, Kotlin positioning 2. notes/consumerapps.md — Pricing, features, platforms, USPs (15 apps) 3. notes/professionalapis.md —…

Mapping the Astrology App Competitive Landscape

Western apps dominate U.S. revenue through social features and live-reading upsells; Vedic apps hold India with 70M+ downloads and consultation marketplaces. With calculation…

Competitive Landscape — Visual Guide

Four charts show what competitors ship, where that depth lives, what they charge and which engine sits underneath.

Astrology Platform Feature Comparison Matrix

Consumer Astrology Apps Competitor Analysis

1. Revenue/download precision: Sensor Tower and data.ai need paid subscriptions; estimates vary. 2. Astra: the 2025 download leader, but little public information. 3.…

Professional Astrology APIs and Platforms — Competitor Analysis

Vedic Astrology Platforms — Competitive Research

Sources: - AstroSage features: Google Play listing - ClickAstro languages: ClickAstro horoscope page - Drik Panchang: App description, Settings - Parashara's Light: Feature…

Package and module guides

See the architecture and dependency HLD for runtime ownership and every direct production workspace dependency.

adapter-contract module

Consumer workspace packages declare "@astrology/astronomy-contracts": "workspace:" in their dependencies. Build the contract before its consumers with pnpm build:ephemeris,…

astrology-semantics module

// adapter is any EphemerisAdapter; the facade owns execution and response assembly. const normalized = new NormalizingAdapter(adapter); const positions = await…

canonical-normalizer module

const astronomy = new NormalizingAdapter(new SwissAdapter()); const result = await astronomy.positions({ instant: '2000-01-01T12:00:00Z', bodies: ['sun', 'moon'], zodiac:…

provider-router module

const swiss = new SwissAdapter(); const capabilities = await swiss.capabilities(); const router = new ProviderRouter([{ capabilities }]); const adapters = new…

swiss-ephemeris-adapter module

The shared logger emits operation summaries at debug, explicit capability probe completion at info, and worker capacity/provider failures at warn. Events are emitted in the…

nasa-adapter module

The shared logger records completed operations at debug and failures at warn, with error codes and body counts only. Requests, coordinates and response text are never logged.

ephemeris-binder module

Declare "@astrology/ephemeris/node": "workspace:" in the consumer's dependencies. Run pnpm setup:ephemeris once to provision the pinned Swiss files, then pnpm build:ephemeris.

chart-core module

Assembles supplied astronomical facts into a reference frame, house placements and body rosters.

Reading the Chart Composer

Chart Composer turns completed astronomical reads into neutral chart facts. It serves both the Vedic and Western engines; those engines add their own judgments afterward.

contracts module

The shared TypeScript vocabulary for chart inputs, snapshots, geometry and injected ports.

context module

Validates explicit chart choices and decides when acquired facts or chart coordinates are compatible.

evidence module

Creates deterministic calculation identities and retains distinct contributing source records.

geometry module

Evaluates aspect contacts (named angular relationships between points) and directed house overlays through the existing semantics helpers.

probes module

See the reading guide for the session's state and reading order.

composer module

The public shared facade composes neutral snapshots for either engine. It contains no tradition rules and never imports or constructs Binder or a provider. Host code resolves…

ashtakavarga module

Natal Bhinna and Sarva Ashtakavarga, the bindu (point) tables that score how strongly each sign is supported by the planets. Public imports use the package root. See the…

chart-judgments module

D1 dignity, combustion and planetary war (two planets closer than one degree, one declared the winner) over Composer facts. Public imports use the package root. See the…

contracts module

Shared Vedic identities, result envelopes, feature contract and upstream ports. Public imports use the package root. See the package specification and task plan (V-16).

dasha module

Vimshottari (Vimshottari dasha, the 120-year cycle of nine planetary periods) birth balance, nested timeline and active-period lookup. Public imports use the package root.…

drishti module

Policy-aware Vedic graha drishti relationships: the whole-sign aspects a planet casts by counting signs from its own. Public imports use the package root. See the package…

engine module

Public Vedic coordinator, dependency planning and evidence. Public imports use the package root. See the package specification and task plan (V-15).

host module

Registers Vedic calculation modules with createVedicEngine and exposes the result as one transport-neutral service for an HTTP layer. See the host assembly order (steps 3–5).

matching module

Ashtakoota matching, the eight-factor (koota) compatibility score out of 36, over two sets of Moon facts. Public imports use the package root. See the package specification…

muhurta module

Purpose-pack muhurta (auspicious time window) selection over calculated panchang days. Public imports use the package root. See the package specification and task plan (V-13,…

panchang module

Sunrise-anchored five limbs of the panchang, the Vedic calendar day, with solved boundary instants. Public imports use the package root. See the package specification and…

profiles module

Internal Vedic convention selection. Public service types are exported from the package root. See the package specification and task plan (V-01).

rulebooks module

Rulebook registry, bundle integrity and version admission. Public imports use the package root. See the package specification and task plan (V-17).

strengths module

Audited strength factors with explicit completeness. Public imports use the package root. See the package specification and task plan (V-06, V-19).

transit module

Gochara (Vedic transits counted from the natal Moon sign), vedha, Sade Sati and solved transit windows. Public imports use the package root. See the package specification and…

upstream module

Adapter and binder layer that connects upstream astronomy ports as they become available. Public imports use the package root. See the package specification and task plan.

varga module

D1-to-divisional mapping, varga frames (divisional charts that split each sign into equal or unequal parts) and vargottama (same sign in D1 and D9). Public imports use the…

yoga-dosha module

Named yoga/dosha rule packs (planetary combinations and afflictions) over supplied facts. Public imports use the package root. See the package specification and task plan…

composite module

Implements composite@1/midpoint, the composite chart built from the midpoints of two charts: shorter-arc body/ASC (Ascendant, the rising degree)/MC (Midheaven, the…

contracts module

Western domain contract shared by the engine and its technique packages. Public imports use the package root. See the package specification and task W-12.

directions module

Implements directions@1/solar-arc-naibod, a solar arc direction that moves every point by the same arc. calculateSolarArc({ reference, targetInstant }, rules) advances…

engine module

Western coordinator: profile and rulebook resolution, upstream binding, technique planning and the result envelope. Public imports use the package root. See the package…

harmonics module

Implements harmonics@1/harmonic-n, the harmonic chart. transformHarmonic(snapshot, factor, rules) multiplies body, ASC (Ascendant) and MC (Midheaven) longitudes by an elected…

host module

The service exposes the coordinator's capabilities, compose, chart and operation methods, plus the registered technique names and profile/rulebook identities. Requests still…

natal module

Pure Western natal judgments over admitted chart facts: element/modality distribution, house emphasis, rulership, essential dignity and aspect/sign patterns. Public imports…

profiles module

Versioned Western convention catalog plus the adapter that turns a resolved profile and request values into the shared Composer chart request. Public imports use the package…

progressions module

Implements progressions@1/secondary-day-for-year, the secondary progression that equates one day after birth with one year of life. mapProgressionContext({ reference,…

returns module

Implements returns@1/solar, the solar return: search for the reference Sun longitude, then cast a chart at a unique solved instant under an explicit location policy. Lunar,…

rulebooks module

Western rulebook admission: manifest validation, content-hash integrity and typed technique lookup. Public imports use the package root. See the package specification and…

synastry module

Implements synastry, the comparison of two people's charts. Compares two already-admitted Composer snapshots using an injected GeometryPort. The ordered source/target pair…

transit module

Implements transits, the comparison of current sky positions with a reference chart. Compares elected moving/reference body pairs using Composer geometry. The natal reference…

upstream module

Adapter and binder layer that connects upstream astronomy and geometry ports as they become available. Public imports use the package root. See the package specification and…

binder-client module

Wrap an already initialized Binder with createBinderReader(binder). Binder is imported only as a type. Host code owns provider construction, resolution of Terrestrial Time…

host module

Shared host assembly for both tradition services: wraps an initialized Binder with createBinderReader and builds one Composer with explicit probe limits (steps 1–2 of the…

logger module

const applicationLogging: LoggingPlugin = { name: 'application-profile', configure: ({ environment }) => ({ level: environment.APPPROFILE === 'production' ? 'warn' : 'info',…

drift-validator module

// Supply dedicated uncached EphemerisAdapter instances from the background worker host. // A future NASA/Horizons adapter can implement the existing contract. const…

@astrology/api-service

Transport-neutral service layer behind the HTTP API. It holds every operation the Express controllers expose, so code in the same process can call them directly with no HTTP…