The full weighted-scoring RFC for this decision lives in the TPM portfolio: home-grown-ephemeris-engine.md. This page is the product-frame summary.
For a commercial API targeting developers who pay for accuracy and uptime, where does the astronomy math come from?
- Wrap an MIT library like
circular-natal-horoscope-js(v0 did this) - Wrap the dominant astronomy library — dual-licensed GPL / commercial
- Proxy a paid API (AstrologyAPI, Prokerala)
- Build from primary sources (Meeus, IMCCE VSOP87, ELP2000, Standish)
| Option | Accuracy | Licensing | Unit economics | Defensibility | Ship time |
|---|---|---|---|---|---|
| 1 — wrap MIT lib | 🔴 multi-degree errors | 🟢 | 🟢 | 🔴 none | 🟢 already done |
| 2 — dominant lib | 🟢 best in class | 🔴 GPL or pay-per-deal | 🟡 | 🟡 | 🟡 |
| 3 — proxy paid API | 🟢 their accuracy | 🔴 ToS kills resale | 🔴 gross margin dies | 🔴 none | 🟢 |
| 4 — build from primary | 🟢 ~1″ claimable | 🟢 we own it | 🟢 CPU-only marginal cost | 🟢 permanent | 🔴 hard |
Licensing. Customers ship our math into their apps. If our engine carries a GPL chain, every integration meeting becomes a legal review. That friction kills dev-tool sales. If we proxy a paid API, we're resellers with no leverage.
Margin. A hosted-API proxy at $49/mo Studio tier is gross-margin negative at meaningful scale. First principles means marginal cost = CPU only.
Moat. If the engine is someone else's library, any competitor can do the same wrap in a weekend. The ~40K lines of VSOP87 + ELP2000 + Vedic + Hellenistic math is the defensibility. Every month it runs in production, it accrues more golden-file coverage, more edge-case handling, and more stability the customer depends on.
The math is public. Textbook-level. Not a research problem.
- Meeus ch. 25 — Sun position with elements of Earth's orbit
- Meeus ch. 47 — Moon position via truncated ELP2000
- IMCCE VSOP87 FTP — planetary theory as fixed-width coefficient files
- Standish JPL — Keplerian elements for Pluto and asteroids
- Meeus ch. 9, 12, 15, 21, 47 — time, sidereal, sunrise/sunset, obliquity, nutation
Every single subsystem in the engine is a published algorithm with published tables for validation. The work is not inventing; it's translating mature references into clean TypeScript with a coherent response schema.
That's why a one-day sprint was viable. Not because it's fast math — because it's well-defined math with published validation data. See 07 · Test strategy.
- Coverage depth — the dominant astronomy library handles bodies we don't (extra asteroids, hypothetical planets, some obscure lunar points). These are tail-demand; covered in roadmap.
- Pluto accuracy — Standish Keplerian gives ~1° for Pluto vs the dominant library's ~1″. Documented in the accuracy table. Revisit if real customers complain.
- Eclipse timing at extreme latitudes — our Placidus and sunrise solvers throw at poles. Intentional — graceful degradation would hide a real edge case.
None of these surface for the five target segments (see 01 · Problem & market). If they do, the engine is ours to upgrade.
The VSOP87 evaluator was simpler than expected — a polynomial-in-τ summation of cos(B + C·τ) series, plus bookkeeping. ~200 lines of evaluator, plus ~30K lines of coefficient data auto-generated by scripts/generate-vsop87.mjs parsing the IMCCE fixed-width format. The hard part is never the algorithm; it's the data pipeline and the tests.
The Vedic yoga-detection logic was harder than any planetary theory. Twelve canonical yogas, each with multi-condition rules (house ownership, aspect requirements, dispositor chains) that overlap and occasionally contradict in the literature. That file has more comments than code.
Build from primary sources. Shipped in one focused day because the research and scoping were done ahead. RFC in the TPM portfolio captures the full weighted score.