astrology design library
Ephemeris4 MIN READ12 / 31

Calculation Facade — High-Level Design

Scope decision: This standalone component is dropped from the binder package plan. The design below is historical context. Consumer applications own this responsibility; see the current package architecture.

Status: Draft for review · Part of: Astro Binder · Updated: 2026-10-24

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

1. Purpose

Provider choice must not change the API contract. Otherwise each endpoint decides its own cache, fallback and precision, and two features can disagree about the same instant. The facade decides once:

  • one request → one provider → one response;
  • a cache hit and a fresh calculation share one shape;
  • degradation is declared, never silent;
  • provenance is emitted once, after the answer.

2. Where it sits

REST API /v1 ──▶ calculation facade ──▶ response
                     │
   cache · router · adapters · normalizer · semantics · provenance
  • Upstream: the REST API, which validates transport, shape and instant.
  • Downstream: adapters, normalizer and semantics, through their own contracts.
  • Never: parses HTTP, translates provider flags, converts units or derives astrology.

3. Responsibilities

Stage Owns Refuses to do
Admit Canonical request and absolute instant Parse transport or resolve a timezone
Cache-or-compute Read-through before any provider call Store or re-normalise cache values
Route and call One router decision, one adapter invocation Choose a second provider or merge answers
Normalise and enrich Hand-off to normalizer, then semantics Re-scale units or re-apply an ayanamsa
Assemble data + meta, flags and precision Invent metadata the normalizer did not stamp
Degrade Fail closed, flag reduced precision Silent substitution or silent precision loss
Emit audit One provenance record after assembly Block the response or retry into it

4. Architecture

Calculation Facade — High-Level Design Reference design. The REST API hands the calculation facade a canonical request. The facade checks the result cache, asks the provider router for one provider decision, calls that adapter, hands the raw answer to the canonical normalizer and then to astrology semantics, assembles the response with provenance and degradation flags, and emits one audit record after the response. It never substitutes a provider or hides a precision loss. Calculation Facade — High-Level Design One orchestration point for every calculation: route, normalise, enrich, degrade honestly and answer. REST API · /v1 validated canonical request absolute instant only Calculation facade · orchestration and response ownership Admit canonical request only no provider knowledge Cache-or-compute read-through before any call one provider per response Assemble response data + provenance meta degradation flags request Result cache provider + request key engine version in key read-through select Provider router capability matrix fallback · breaker · quota Swiss + NASA adapters swe_* calls · Horizons query raw provider answer Canonical normalizer units · frame · zodiac single rounding point Astrology semantics signs · nakshatras · aspects provider-independent call raw answer canonical values values + annotations Provenance store one record per response written off the response path async audit record Degradation policy Fail closed, never substitute a provider, never hide a precision loss. A cache hit skips compute, not provenance. dependency after-response work module entry / saved state boundary

Diagram: reference design, not deployed behaviour.

The facade is an ownership boundary, not a fourth provider. Its collaborators have their own designs; it orders their work and decides the outcome.

5. Rules

  1. One provider per response. One provenance block means one adapter call.
  2. Cache is read-through. A hit returns stored values and provenance without an adapter call or re-normalisation; only cacheHit differs.
  3. Fail closed. If no eligible provider can serve, return PROVIDER_UNAVAILABLE; never hide a Swiss outage behind Horizons.
  4. Degrade explicitly. Moshier answers (built-in low-precision ephemeris) carry degraded: true and reduced precisionArcsec; uncovered answers are OUT_OF_EPHEMERIS_RANGE unless the configured fallback applies.
  5. Compose, do not calculate. Normalizer and semantics own positions, houses and meanings; the facade adds no rules.
  6. Provenance after the answer. Emit the record once the response exists; it never gates the return.
  7. Stable shape. Cache hit, fresh compute and degraded compute share fields; clients branch on flags, not variants.
  8. No hidden retries. The adapter maps timeouts; the facade never loops across providers.

6. Edge cases

Case Behaviour
Cache hit Stored values and provenance returned; cacheHit: true; no re-normalisation
Cache unavailable Treated as a miss; the provider path runs
Swiss worker down 503 PROVIDER_UNAVAILABLE; no substitution
Moshier fallback used Answer returned with degraded: true and lower precision
File coverage gap, fallback disabled 422 OUT_OF_EPHEMERIS_RANGE
Horizons slow or down No user impact; drift validation pauses
Normalizer rejects the answer 500 INTERNAL with a correlation id; no partial body
Provenance write fails Response still returned; failure counted

7. Out of scope

  • HTTP validation and problem+json mapping (REST API).
  • Capability, coverage and breaker policy (provider router).
  • Provider protocol and error translation (adapters).
  • Unit, frame, zodiac and provenance stamping (normalizer).
  • Signs, nakshatras, aspects and house placement (semantics).
  • Cache and provenance persistence (their stores).
  • Drift comparison and alerting.

8. Planned code

Piece Responsibility
facade/CalculationFacade Orchestration and the single response path
facade/RequestAdmission Canonical request checks and absolute instant
facade/CacheCoordinator Read-through and hit metadata
facade/ProviderInvoker Router decision to one adapter call
facade/ResponseAssembler data + meta, flags and precision
facade/DegradationPolicy Fail-closed and reduced-precision decisions
facade/ProvenanceEmitter One post-response audit record