Astrolinkers — Programmatic Astrology API

The problem

Astrology software is often split into two weak forms: consumer horoscope apps with shallow interpretations, or old calculation tools that are hard to integrate into modern products. Astrolinkers is built for the missing middle: a programmable astrology API that other builders can use inside products, workflows, internal tools, and experiments.

The product promise is deliberately technical: one REST API for natal charts, talent profiles, pair compatibility, template interpretations, optional AI rewrites, async PDF reports, and a broad Vedic calculation engine. The public site positions it as "programmatic natal charts, talent profiles & compatibility — for builders", with a free maker tier, dashboard, live demo, and official Python and TypeScript SDKs.

What the product does

Astrolinkers turns birth-time data into structured astrology outputs. The core API creates Western or Vedic natal charts, derives talent profiles from a skill ontology, generates template-based interpretations, computes pair compatibility, collects per-statement feedback, and produces HTML/PDF reports through an async worker pipeline.

The Vedic side is intentionally deep rather than decorative: divisional charts, bhava chakra, Parashara drishti, dignity, functional nature, Vimshottari dasha, yogas, Ashtakavarga, Shadbala, Panchanga, Jaimini karakas, arudha, progressions, transits, Varshaphala, KP sub-lords, and muhurta optimization are exposed through documented endpoints.

The system is in beta, but not in the "mockup" sense. It has a public marketing site, public API documentation, dashboard entry points, live demo endpoint, self-service API keys, rate limits, typed SDKs, and production-oriented operational controls.

What I built

The backend platform. I built the API as a clean-architecture Python service: FastAPI at the edge, application use-cases in the middle, domain types and protocols at the core, and concrete adapters for Postgres, Redis, RabbitMQ, object storage, email, LLM providers, and Swiss Ephemeris.

Astrology calculation layer. The core uses Swiss Ephemeris through a dedicated adapter and wraps both Western and Vedic calculations behind stable service boundaries. The public contract is JSON in / JSON out; internally, the goal is reproducibility, testability, and a path to extract the calculation engine later if it becomes a performance bottleneck.

Talent profile and interpretation pipeline. A skill ontology maps chart-derived signals into soft and hard skill scores. Template-based statements give deterministic output, while the LLM layer can rewrite interpretations by tone without making the LLM the source of truth.

Async reports. Heavy report generation is not handled as a long HTTP request. A report is enqueued, processed by workers, rendered to HTML/PDF, stored in object storage, and returned through a signed download flow.

Production controls. The platform includes JWT/bearer auth, API-key issuance and revocation, tenant isolation, deny-by-default scope checks, idempotency for mutating requests, rate limiting, quota and usage tracking, audit middleware, structured errors, readiness probes, metrics, tracing, and Sentry integration.

SDKs and developer experience. I also shipped public docs and official SDKs: Python (astrolinkers-sdk) and TypeScript (@astrolinkers/sdk-ts). The SDKs expose typed methods, response validation, retry behavior, and typed errors so users do not have to hand-roll HTTP calls.

Architectural choices

Modular monolith first. The system is one codebase with multiple processes: API, worker, and scheduler. That keeps delivery fast while preserving clear seams around astrology, reports, interpretations, feedback, auth, usage, and API keys. If a domain needs to split later, the ports already exist.

LLM as an adapter, not the architecture. Astrolinkers has AI interpretations, but the platform does not depend on a single model. LLM providers sit behind protocols and routing policy, with fallbacks, cost tracking, latency tracking, and deterministic template output as the baseline.

Feedback as the moat. Every interpretation statement can collect accuracy feedback. That turns subjective interpretation quality into data: template accuracy can be aggregated, weak rules can be found, and future scoring can be improved from real user judgment rather than guesses.

Observable from day one. The system exposes Prometheus metrics, OpenTelemetry traces, structured logs, /healthz, /readyz, /version, and operational SLOs. This is important because astrology calculation, LLM providers, worker queues, and PDF rendering fail in different ways.

Beta with production discipline. Astrolinkers is currently in beta, but it is treated as a real production service: versioned API, documented error envelope, rate limits, tenant boundaries, runbooks, SLOs, deployment manifests, and soft-launch gates.

Current status

Astrolinkers is live at astrolinkers.com, with public documentation at docs.astrolinkers.com. The dashboard lives at app.astrolinkers.com, and the public site includes a live chart demo against the same calculation engine users hit through the API.

I built the project solo: product framing, backend architecture, astrology engine integration, API contract, auth and quotas, report pipeline, docs, SDKs, deployment posture, and operational hardening. The next stage is expanding beta usage, tightening feedback loops, and turning real usage data into better interpretation quality and clearer commercial packaging.