# Astrolinkers — программируемый astrology API

Production-grade API для астрологических продуктов: Western и Vedic natal charts, talent profiles, compatibility, interpretations, async PDF reports, API keys, публичные docs, SDK и live demo. Сделан solo и сейчас работает в beta как реальный продукт.

- **Author:** Фёдор Чищин
- **Role:** Solo founder-engineer
- **Period:** 2025 — настоящее
- **Stack:** Python · FastAPI · SQLAlchemy (async) · PostgreSQL · Redis · Dramatiq · Swiss Ephemeris · WeasyPrint · S3-compatible storage · Anthropic / OpenAI / Ollama · MCP · OpenTelemetry · Next.js
- **Source:** https://fedorthinks.com/ru/work/astrolinkers

---

## Проблема

Астрологический софт часто существует в двух слабых формах: consumer-приложения с поверхностными
гороскопами или старые расчётные инструменты, которые трудно встроить в современный продукт.
Astrolinkers закрывает промежуток между ними: программируемый astrology API, который разработчики
могут использовать в своих продуктах, workflow, внутренних инструментах и экспериментах.

Обещание продукта намеренно техническое: один REST API для natal charts, talent profiles, pair
compatibility, template interpretations, optional AI rewrites, async PDF reports и большого Vedic
calculation engine. Публичный сайт позиционирует продукт как "programmatic natal charts, talent
profiles & compatibility — for builders": есть бесплатный maker tier, dashboard, live demo и
официальные Python/TypeScript SDK.

## Что делает продукт

Astrolinkers превращает данные рождения в структурированные астрологические результаты. Core API
создаёт Western или Vedic natal chart, строит talent profile через skill ontology, генерирует
template-based interpretations, считает pair compatibility, собирает feedback по каждому statement
и создаёт HTML/PDF отчёты через асинхронный worker pipeline.

Vedic-часть сделана глубокой, а не декоративной: divisional charts, bhava chakra, Parashara
drishti, dignity, functional nature, Vimshottari dasha, yogas, Ashtakavarga, Shadbala, Panchanga,
Jaimini karakas, arudha, progressions, transits, Varshaphala, KP sub-lords и muhurta optimization
вынесены в документированные endpoint-ы.

Сейчас система в beta, но это не "макет". Уже есть публичный marketing site, public API docs,
dashboard entry points, live demo endpoint, self-service API keys, rate limits, typed SDK и
production-oriented operational controls.

## Как выглядит продукт

## Что я построил

**Backend platform.** Я построил API как clean-architecture Python service: FastAPI на edge,
application use-cases в середине, domain types и protocols в ядре, concrete adapters для Postgres,
Redis, очередь задач Dramatiq, object storage, email, LLM-провайдеры (Anthropic, OpenAI и
self-hosted Ollama) и Swiss Ephemeris.

**Astrology calculation layer.** Core использует Swiss Ephemeris через отдельный adapter и закрывает
Western/Vedic расчёты стабильными service boundaries. Публичный контракт — JSON in / JSON out; внутри
цель — воспроизводимость, тестируемость и путь к выделению calculation engine, если он станет
performance bottleneck.

**Talent profile и interpretation pipeline.** Skill ontology маппит chart-derived signals в soft и
hard skill scores. Template-based statements дают детерминированный baseline, а LLM layer может
переписывать интерпретации по tone, не становясь source of truth.

**Async reports.** Тяжёлая генерация отчёта не делается длинным HTTP-запросом. Report enqueue-ится,
обрабатывается worker-ами, рендерится в HTML/PDF, сохраняется в object storage и отдаётся через
signed download flow.

**Production controls.** В платформе есть JWT/bearer auth, выпуск и отзыв API keys, tenant
isolation, deny-by-default scope checks, idempotency для мутаций, rate limiting, quota и usage
tracking, audit middleware, structured errors, readiness probes, metrics, tracing и Sentry
integration.

**SDK и developer experience.** Я также сделал public docs и официальные SDK: Python
(`astrolinkers-sdk`) и TypeScript (`@astrolinkers/sdk-ts`). SDK дают typed methods, response
validation, retry behavior и typed errors, чтобы пользователям не приходилось вручную собирать HTTP
клиент.

## Архитектурные решения

**Modular monolith first.** Система — один codebase с несколькими процессами: API, worker и
scheduler. Это сохраняет скорость разработки, но даёт ясные границы вокруг astrology, reports,
interpretations, feedback, auth, usage и API keys. Если домен нужно будет выделить позже, ports уже
есть.

**LLM как adapter, а не архитектура.** В Astrolinkers есть AI interpretations, но платформа не
зависит от одной модели. LLM providers находятся за protocols и routing policy, с fallback-ами,
cost tracking, latency tracking и deterministic template output как базовой линией.

**Feedback как moat.** Каждый interpretation statement может собирать accuracy feedback. Это
превращает субъективное качество интерпретаций в данные: можно агрегировать template accuracy,
находить слабые правила и улучшать scoring на реальных оценках пользователей, а не на догадках.

**Observable from day one.** Система отдаёт Prometheus metrics, OpenTelemetry traces, structured
logs, `/healthz`, `/readyz`, `/version` и имеет описанные SLO. Это важно, потому что astrology
calculation, LLM providers, worker queues и PDF rendering ломаются по-разному.

**Beta с production-дисциплиной.** Astrolinkers сейчас в beta, но ведётся как реальный production
service: versioned API, documented error envelope, rate limits, tenant boundaries, runbooks, SLO,
deployment manifests и soft-launch gates.

## Текущее состояние

Astrolinkers доступен на [astrolinkers.com](https://astrolinkers.com), публичная документация — на
[docs.astrolinkers.com](https://docs.astrolinkers.com). Dashboard живёт на
[app.astrolinkers.com](https://app.astrolinkers.com), а публичный сайт включает live chart demo
против того же calculation engine, который используется через API.

Я сделал проект solo: product framing, backend architecture, astrology engine integration, API
contract, auth и quotas, report pipeline, docs, SDK, deployment posture и operational hardening.
Следующий этап — расширять beta usage, усиливать feedback loops и превращать реальные данные
использования в более качественные интерпретации и понятную коммерческую упаковку.