A little clarity.
The whole system.

Astrology vocabulary, bottom up

Start with a definition, understand why the concept exists, then follow a worked example. This guide separates sky geometry, astrological conventions and software…

Layer 0 — The sky and the clock

An ephemeris supplies a body's position at an instant. A chart adds derived values, including signs, houses and aspects. Positions need a timestamp and a named coordinate…

Binder and architecture terms

These describe software responsibilities. A provider supplies astronomical calculations; a frame states the reference origin, plane and direction conventions used to express…

Glossary A–Z

Guide index · A–Z lookup · Sources

Layer 5 — Charts and time techniques

“Natal” means relating to birth. A chart is a calculated map for an instant and place, not just a Sun sign. The radix (root chart) is the reference chart used in later…

Sources and how to read them

Astronomical definitions describe geometry and time. Astrological rules describe a named tradition. Product research records what a product offered at the research date.…

Layer 6 — The Vedic stack

Jyotish reuses Layers 0–2 and adds finer divisions plus a time system: signs and nakshatras are overlapping grids, padas subdivide nakshatras, and dashas assign time periods…

Layer 7 — Delivery and rendering

Calculation is only half the product. This layer is what the user sees and what developers integrate with.

Layer 3 — Bodies

A chart is a set of bodies with positions, speeds and flags. "Planet" is shorthand: the catalogue above runs from the Sun to hypothetical points, and not all of them are…

Layer 1 — The zodiac and the ayanamsa

The sky of Layer 0 gives us longitudes — but a longitude is a number, and a number needs a zero point. This layer is entirely about that zero point: where the measuring…

Layer 2 — Signs, houses and angles

Layer 0 fixes where a body is; Layer 1 fixes what the longitude counts from. This layer slices the sky into signs (a global lattice on the ecliptic) and houses (a local frame…

Layer 4 — Aspects

An aspect is a specified angular relationship between chart points. The word comes from the idea of looking or regarding: traditional astrology describes planets as “seeing”…

Data examples

These JSON blocks are teaching sketches, not generated schemas or the implemented API contract. They show which concepts travel together. For actual request fields and…

Ephemeris

Designs for the astronomy layer behind every astrology calculation: planetary and lunar positions, houses, zodiac and ayanamsa handling, and their provider contracts.

Astro Binder — Package Architecture

Astro Binder is a collection of reusable TypeScript packages for astronomical calculations. Consumer applications choose the packages they need and own execution, lifecycle…

Swiss Ephemeris adapter — workspace module

The reusable @astrology/swiss-ephemeris-adapter package implements the standalone @astrology/adapter-contract port. Consumers import it into their own applications. Neither…

Swiss adapter module implementation

The implemented slice consists of two reusable TypeScript ESM workspace packages: adapter-contract and swiss-ephemeris-adapter. The former HTTP host, routes, HTTP status…

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/nasa-adapter workspace package. It maps the HLD onto the @astrology/adapter-contract, 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, nakshatras, padas, motion, aspects and houses. It is pure, in-process, with no provider, network, clock or locale.

Drift Validator — High-Level Design

The drift validator recomputes sampled cases with Swiss Ephemeris and JPL Horizons, then alerts if the primary engine drifts from it. It never runs on a request path.

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

Each response yields one immutable audit record: the provider, engine version, ephemeris files, flags and precision behind its values. No request body is stored.

Astrology

Designs for the chart layer above the ephemeris: how canonical positions become natal charts, divisional charts, dashas, panchang, transits, compatibility, and muhurta.

Astro Composer — High-Level Design

Astro Composer turns canonical astronomy into astrology charts. It reads positions and houses from Astro Binder and composes natal charts, vargas (divisional charts),…

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

This register records the rules the composer must pin, where implementations disagree, what the binder can supply, and how the result is validated. It lets a reviewer…

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…