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 and transport. There is no binder server or mandatory all-in-one facade.
Start with the vocabulary, then follow the package guides below. Astro Composer explains how the primitives become chart features.
Package decisions
Keep the shared contract, adapters, routing, normalization, semantics, drift validation and logging as separate workspace packages. A feature can reuse meaning without importing a native provider or starting a background job.
| Package | Owns | Guide |
|---|---|---|
@astrology/adapter-contract |
Shared requests, results, validation, capabilities and typed errors | Contract boundary |
@astrology/swiss-ephemeris-adapter |
Swiss computation, ephemeris files and native worker lifecycle | Swiss adapter |
@astrology/nasa-adapter |
Horizons HTTP queries, response parsing and transport limits | NASA adapter |
@astrology/provider-router |
One eligible provider decision for a complete request | Router |
@astrology/canonical-normalizer |
Canonical-answer validation, angle wrapping, rounding and provenance | Normalizer |
@astrology/astrology-semantics |
Signs, nakshatras, motion, aspects and house placement | Semantics |
@astrology/drift-validator |
Background comparison through injected adapters and host hooks | Drift validator |
@astrology/logger |
Shared package logging configured by the host | Logging ownership |
These are workspace modules, not separately hosted services. Source presence does not establish deployment, a successful live NASA comparison or production accuracy.
Logging ownership
The host configures logging once; packages use their own tagged loggers. Root and package levels, environment overrides, configuration plugins and reporters belong to that shared configuration. Logging does not provide durable provenance storage or drift-alert delivery.
Dropped from binder scope
A standalone calculation facade, result-cache service and provenance-store service are dropped from the binder package plan. Consumers own orchestration, optional persistence, scheduling and presentation. Integration hooks do not require separate binder services.
Earlier facade, cache and provenance-store designs remain for context. They are historical proposals, not remaining binder deliverables. Returning provenance is still supported; persisting it is a separate host choice.
How the architecture fits together
The contract defines the shared language. Adapters translate provider APIs into that language. The router chooses a provider but never invokes it. The normalizer checks the answer and rounds it once. Semantics derives astrology labels from the geometry. The host connects these steps.
For example, a sidereal longitude of 33° means Taurus at 3° within the sign. Semantics can
also resolve its nakshatra and
pada, without another provider call or
subtracting an ayanamsa again.
A calculation in a consumer application
- Resolve civil date, time and timezone to an absolute instant. Shared validation rejects bare local times; the packages do not supply a timezone database.
- When routing is needed, discover capabilities and supply the matching TT Julian Day. The host owns time resolution and capability refresh.
- Invoke the selected adapter, optionally through
NormalizingAdapter. A direct Swiss consumer can omit routing. - Retain the provider declaration and normalization evidence. Current adapters already map identifiers, units and frames; the normalizer checks this contract. It does not turn tropical NASA positions into sidereal positions.
- Apply the semantics needed by the feature and assemble the application response. Optional cache retrieval/storage and provenance persistence belong to the host.
Drift validation is a separate host-run batch using dedicated resources. It recomputes tropical, geocentric cases through injected adapters and compares compatible answers. Constructing the validator starts no timer or process. Scheduling, durable storage and alert delivery need host integrations; per-run aggregates do not imply a daily history service.
Provider policy
Swiss is the default primary. All requested bodies must fit one provider; answers are never merged across providers. Coverage fallback is disabled by default and explicitly names registered providers and allowed bodies. It applies only to tropical positions when primary body/date coverage is missing. Outages, open breakers, quotas, houses and sidereal requests do not authorize fallback.
Horizons supplies tropical positions, not houses, lunar nodes or native sidereal modes. Its adapter controls network deadlines and concurrency. Topocentric calls require explicit configuration because they send observer coordinates to NASA. See the NASA module guide for settings and limits.
Geometry, meaning and evidence
| Concept | Meaning |
|---|---|
| Longitude | Decimal degrees around the ecliptic, wrapped into [0, 360) |
| Zodiac | Tropical or sidereal reference zero point |
| Houses | Twelve observer-dependent divisions; a house is not always a sign |
| Motion | Derived from longitude speed; missing speed means unknown |
| Aspects | Angular relationships judged against a chosen tolerance profile |
| Provenance | Evidence identifying the provider, engine, files, time model and normalization policy |
Decimal places are not astronomical accuracy. Rounding to eight decimals does not establish eight-decimal precision. Unknown accuracy remains unknown. Packages reject with typed error codes; consumers choose HTTP statuses or UI messages.
Reading the older designs
Detailed component guides retain reference designs alongside current implementation notes. Read their scope notes first: older endpoints, persistence flows and delivery phases are not promises of the package API.
The earlier architecture diagram includes the dropped facade, cache and provenance services. It is a historical reference. The package table and ownership explanation above describe the current boundary.
Outside the binder
Astro Composer combines these primitives into natal charts and later calculations. Birth-record storage, saved charts, interpretation and application APIs stay outside the binder. Consumers own licensing review, deployment, ephemeris provisioning and safe handling of birth times and coordinates.