- horoscope-api: Swiss Ephemeris natal charts, timezone/place resolution, POST /v1/natal and POST /v1/synastry - backend: users with roles, email/password and Google login, saved charts, synastries and invites, analyses with credit ledger, public shares, admin - shared crates: astro-engine, db (migrations), horoscope-client, service-kit - docker-compose with postgres, legacy Java project for reference Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012vLHzh5qUhFtmJhzkcTbXL
Sorsfonalak – backend szolgáltatások
Asztrológiai rendszer konténeres backendje. A frontenden kívül minden Rustban készül.
| Komponens | Leírás |
|---|---|
services/horoscope-api |
HTTP API: születési adatokból születési horoszkóp (radix) és szinasztria |
services/backend |
felhasználók, belépés, mentett képletek, szinasztriák, meghívók, elemzések, kreditek, megosztás. Részletek: services/backend/README.md |
crates/db |
PostgreSQL-séma (migrációk) és a szolgáltatások közös adatelérése |
crates/horoscope-client |
a horoscope-api HTTP-kliense (a backend és később a worker használja) |
crates/service-kit |
közös alapok: naplózás, listen cím, healthcheck, leállítás |
crates/astro-engine |
horoszkópszámítás egy cserélhető efemerisz-motor (Ephemeris trait) fölött; jelenleg Swiss Ephemeris |
crates/swisseph-sys |
FFI a Swiss Ephemeris C könyvtárhoz (a forrás a vendor/swisseph mappába töltődik le) |
crates/geo-tz |
offline helységkeresés (GeoNames) és történeti időzóna-kezelés (IANA tzdb + backzone) |
scripts/fetch-deps.sh |
minden külső adat és forrás letöltése (build-időben, futáskor nincs hálózat) |
legacy/ |
a régi Java/GWT alkalmazás, csak referencia |
Futtatás
Docker
docker compose up -d --build # horoscope-api :8080, backend :8081, postgres 127.0.0.1:5432
curl -s localhost:8080/healthz
curl -s localhost:8081/healthz
A horoscope-api image önálló (scratch alapú, kb. 70 MB, nem root felhasználóval fut). Benne van a statikus bináris és az összes adat. A container induláskor ~2 mp alatt betölti az adatokat, és ~190 MB memóriát használ. Egy horoszkóp kiszámítása 2–3 ms.
Build-argumentumok (docker compose build --build-arg …):
| Argumentum | Alapérték | Jelentés |
|---|---|---|
TZDB_VERSION |
2026f |
IANA tzdb kiadás |
SWISSEPH_VERSION |
v2.10.3bfinal |
Swiss Ephemeris git tag |
SWISSEPH_EPHE_FILES |
sepl_18.se1 semo_18.se1 seas_18.se1 |
adatfájlok (1800–2399); például sepl_12.se1 semo_12.se1 seas_12.se1 kell 1200–1799-hez |
GEONAMES_CITIES |
cities500 |
világszintű helységlista (legalább 500 lakos) |
GEONAMES_FULL_COUNTRIES |
HU |
országok, amelyeknek minden települése bekerül (szóközzel elválasztva, pl. "HU RO SK") |
Helyben
scripts/fetch-deps.sh # vendor/ és data/ letöltése (egyszer)
docker compose up -d postgres # a backend tesztjeihez
export DATABASE_URL=postgres://sorsfonalak:sorsfonalak-dev@127.0.0.1:5432/sorsfonalak
cargo test --workspace # unit + referencia + API + backend integrációs tesztek
cargo run --release -p horoscope-api # http://localhost:8080
A backend tesztjei minden tesztesethez friss, migrált adatbázist hoznak létre a DATABASE_URL szerveren.
Környezeti változók: ASTRO_DATA_DIR (alapérték: data), BIND_ADDR (0.0.0.0:8080), CORS_ALLOWED_ORIGINS (* vagy vesszővel elválasztott lista), LOG_FORMAT (text/json), RUST_LOG.
API
| Végpont | Leírás |
|---|---|
POST /v1/natal |
születési horoszkóp |
POST /v1/synastry |
két ember összevetése: szinasztria és kompozit képlet |
GET /v1/places?country=HU&q=szeged®ion=&limit=10 |
helységkeresés (a frontend helyválasztójához) |
GET /v1/timezones?country=US |
egy ország időzónái |
GET /v1/countries |
országok és időzónáik |
GET /v1/info |
választható opciók, alapértékek, adatverziók |
GET /healthz |
állapotellenőrzés |
POST /v1/natal: kérés
{
"date": "1985-07-14",
"time": "14:30",
"country": "HU",
"place": "Budapest"
}
| Mező | Kötelező | Leírás |
|---|---|---|
date |
✔ | helyi dátum, YYYY-MM-DD (1000–2999) |
time |
helyi idő, HH:MM vagy HH:MM:SS. Ha hiányzik, ismeretlen születési idő: 12:00-ra számol, házak, tengelyek és sorspontok nélkül |
|
calendar |
gregorian (alapérték) vagy julian (pl. Oroszország 1918 előtt); a julián dátumot átváltja gergely-naptárira |
|
country |
✔ | ország: ISO kód (HU, HUN) vagy angol név |
place |
✱ | településnév bármilyen nyelven, ékezettel vagy anélkül (Kolozsvár → Cluj-Napoca) |
region |
megye vagy állam az azonos nevű települések szétválasztására | |
geonames_id |
✱ | pontos hely (a /v1/places válaszából); elsőbbséget élvez a place mezővel szemben |
latitude, longitude |
✱ | koordináták; felülírják a település koordinátáit, és település nélkül kötelezők |
elevation |
magasság méterben (csak topocentrikus számításnál számít) | |
timezone |
IANA zóna felülírása (pl. Europe/Budapest) |
|
utc_offset |
fix UTC-eltérés (pl. +02:00), ha az anyakönyv mást mond, mint a tzdb |
|
ambiguous_time |
reject (alapérték), earlier vagy later: mi legyen az óraátállításkor kétszer előforduló vagy nem létező időponttal |
|
options |
lásd alább | |
name |
tetszőleges címke, a válaszban visszakapod |
✱ A place, a geonames_id és a latitude+longitude közül legalább egy kötelező.
options (minden mezőnek van alapértéke):
| Opció | Értékek (alapérték vastagon) |
|---|---|
house_system |
placidus, koch, porphyry, regiomontanus, campanus, equal, whole_sign, alcabitius, morinus, topocentric, meridian, vehlow |
zodiac |
tropical, sidereal |
ayanamsa |
lahiri, fagan_bradley, raman, krishnamurti, de_luce, yukteshwar, true_citra, galactic_center0_sag (csak sziderikus zodiákusnál) |
node_type |
true, mean: holdcsomópont |
lilith_type |
mean, true: Fekete Hold |
aspect_set |
major (együttállás, szextil, kvadrát, trigon, oppozíció), extended (+ félszextil, félkvadrát, kvintil, másfélkvadrát, bikvintil, kvinkunx) |
orb_multiplier |
1.0 (0 < x ≤ 3) |
topocentric |
false |
include_asteroids |
true (Ceres, Pallas, Juno, Vesta) |
Válasz (rövidítve)
{
"input": { /* a kérés, alapértékekkel kiegészítve */ },
"location": { "country": {...}, "place": {...GeoNames adatok...}, "latitude": 47.49835, "longitude": 19.04045,
"coordinates_source": "place", "alternatives": [ /* további azonos nevű helyek */ ] },
"time": {
"zone": "Europe/Budapest", "zone_source": "place",
"local": "1985-07-14T14:30:00", "utc": "1985-07-14T12:30:00Z",
"utc_offset": "+02:00", "dst": true, "abbreviation": "CEST",
"local_mean_time": "13:46:10", "time_known": true, "calendar": "gregorian",
"transition": null, "notes": []
},
"settings": { /* használt opciók + orbisz-táblázat */ },
"astronomy": { "julian_day_ut": 2446261.0208, "julian_day_tt": ..., "delta_t_seconds": 54.63,
"local_sidereal_time_hms": "09:15:26", "obliquity": {...}, "ayanamsa": null },
"points": [
{ "id": "sun", "kind": "luminary", "longitude": 112.0007, "sign": "cancer", "degree_in_sign": 22.0007,
"degree_in_sign_dms": "22°00'03\"", "decan": 3, "latitude": 0.00005, "distance_au": 1.0165,
"speed": 0.9541, "retrograde": false, "right_ascension": 113.77, "declination": 21.65,
"out_of_bounds": false, "house": 9, "dignities": [] }
/* moon … pluto, north_node, south_node, lilith, chiron, ceres, pallas, juno, vesta */
],
"angles": { "ascendant": {...}, "midheaven": {...}, "descendant": {...}, "imum_coeli": {...},
"vertex": {...}, "antivertex": {...}, "east_point": {...}, "armc": 138.86 },
"houses": { "system": "placidus", "requested_system": "placidus", "cusps": [ { "house": 1, "sign": "scorpio", ... } ] },
"aspects": [ { "point1": "sun", "point2": "mars", "aspect": "conjunction", "orb": 1.09, "max_orb": 10,
"applying": true, "separation": 1.09, "exact_angle": 0, "major": true } ],
"lots": { "fortune": {...}, "spirit": {...} },
"moon_phase": { "elongation": 319.16, "phase": "waning_crescent", "illumination": 0.12, "waxing": false },
"summary": { "elements": {...}, "modalities": {...}, "hemispheres": {...}, "sect": "day",
"chart_ruler": { "ascendant_sign": "scorpio", "traditional": {...}, "modern": {...} },
"retrograde": ["jupiter", "saturn", "uranus", "neptune"] },
"warnings": [],
"meta": { "data_sources": { "ephemeris": {...}, "tzdb_version": "2026f", ... } }
}
Minden azonosító (bolygó, jegy, fényszög, fázis) angol snake_case; a magyar fordítás a frontend feladata.
POST /v1/synastry: kérés
{
"person1": { "name": "A", "date": "1985-07-14", "time": "14:30", "country": "HU", "place": "Budapest" },
"person2": { "name": "B", "date": "1987-02-03", "time": "06:10", "country": "HU", "place": "Szeged" },
"options": { "aspect_set": "major" }
}
A person1 és a person2 ugyanazokat a mezőket fogadja, mint a /v1/natal, kivéve az options mezőt. Az options csak legfelső szinten adható meg, és mindkét képletre érvényes.
Válasz (rövidítve)
{
"person1": { /* a /v1/natal teljes válasza, meta nélkül */ },
"person2": { /* ugyanígy */ },
"settings": { "aspect_set": "major", "orb_multiplier": 1.0, "orbs": [...] },
"aspects": [ // a két képlet közötti fényszögek, a legszorosabb elöl
{ "person1": "mars", "person2": "jupiter", "aspect": "sextile", "nature": "harmonious",
"major": true, "exact_angle": 60, "separation": 60.04, "orb": 0.04, "max_orb": 5 }
],
"house_overlays": { // az egyik ember pontjai (bolygók, csomópontok, Lilith, Chiron, kisbolygók, AC, MC) a másik házaiban
"person1_in_person2": [ { "point": "sun", "sign": "cancer", "house": 9 } ],
"person2_in_person1": [ ... ]
},
"summary": { "aspect_count": 65,
"by_nature": { "harmonious": 27, "challenging": 29, "neutral": 9 },
"by_aspect": { "conjunction": 9, "sextile": 13, "square": 19, "trine": 14, "opposition": 10 } },
"composite": { // felezőpontos kompozit képlet
"method": "midpoint",
"points": [ { "id": "sun", "longitude": 125.67, "sign": "leo", "degree_in_sign_dms": "5°40'03\"", "house": 7 } ],
"angles": { "ascendant": {...}, "midheaven": {...}, "descendant": {...}, "imum_coeli": {...} },
"houses": { "method": "midpoint_of_cusps", "cusps": [...] },
"aspects": [ /* a kompozit pontok egymás közötti fényszögei */ ]
},
"warnings": [],
"meta": {...}
}
- Fényszögek: ugyanazokat a pontokat és orbiszokat használja, mint a születési képlet: a Nap és a Hold nagyobb orbiszt kap, a csomópontok, a Lilith és a Chiron kisebbet. Az alkalmazó/szeparáló jelzés itt nincs, mert két születési képlet között nincs értelme.
nature:- harmonikus: szextil, trigon, kvintil, bikvintil;
- feszült: kvadrát, oppozíció, félkvadrát, másfélkvadrát, kvinkunx;
- semleges: együttállás, félszextil.
- Kompozit: minden pont a két születési pont közelebbi felezőpontja. A házcsúcsok a két születési házcsúcs felezőpontjai, sorrendhelyesen igazítva; a kompozit AC az 1., az MC a 10. házcsúcs.
- Ismeretlen születési idő: ha az egyik ember születési ideje ismeretlen, a tengelyei kimaradnak a fényszögekből, a másik ember pontjai nem kerülnek az ő házaiba, a kompozitnak pedig nincsenek tengelyei és házai. Erről a
warningsmező is szól. - Hibák: az egyik emberre vonatkozó hibánál a hibaobjektumban egy
personmező is van ("person1"vagy"person2"), és az üzenet ezzel kezdődik.
Hibák formátuma: {"error": {"code": "...", "message": "...", "person": "...", "suggestions": [...]}}.
| HTTP | code |
Mikor |
|---|---|---|
| 400 | bad_request, unknown_country, unknown_time_zone, place_country_mismatch, invalid_date_time |
hibás bemenet |
| 404 | place_not_found (suggestions mezővel), unknown_place_id |
nincs ilyen hely |
| 422 | ambiguous_local_time, nonexistent_local_time |
óraátállításkor; az ambiguous_time mezővel kell dönteni |
| 422 | calculation_failed, no_time_zone |
a számítás nem végezhető el |
Időzónák és nyári időszámítás
- Az IANA tzdb
backzoneadatokkal van fordítva. Az alap tzdb 1970 előtt összevon olyan zónákat, amelyek 1970 óta azonosak; Oslót például Berlinhez köti, pedig Norvégiában 1959–1965 között volt nyári idő, Németországban nem. A backzone-nal minden ország megtartja a saját történetét. Magyarország: 1941–1949 és 1954–1957 között volt nyári idő, 1958–1979 között nem, 1980 óta van. - A zóna kiválasztásának sorrendje: a
timezonemező, ha meg van adva → a talált település zónája (GeoNames) → az ország egyetlen zónája → a legközelebbi település zónája ugyanabban az országban (több zónás országokban, pl. USA, Oroszország) → azone.tablegközelebbi referenciapontja. - Kétszer előforduló és nem létező időpontok (őszi és tavaszi óraátállítás): alapértelmezésben hiba, amely mindkét lehetőséget leírja; az
ambiguous_timemezővel lehet dönteni. - Helyi középidő: ahol még nem volt szabványidő (a tzdb
LMT-t ad), ott a születési hely saját helyi középidejét használja (hosszúság/15 óra), nem a zóna referenciavárosáét. 1880-ban Debrecenben ez +01:26:30, Budapesten +01:16:20. - Felülírás: ha az anyakönyv eltér a tzdb-től (háborús idő, helyi szokás), a
utc_offsetmezővel fix eltérés adható meg.
Ismert korlát: a tzdb a mai közigazgatási zónát ismeri. Ha egy terület történelmileg más országhoz tartozott, azt nem követi. Példa: Észak-Erdély 1940 és 1944 között budapesti időt használt, a Europe/Bucharest zóna viszont ezt nem tartalmazza. Ilyenkor a timezone: "Europe/Budapest" vagy a utc_offset mezőt kell megadni.
Számítási motor
- Swiss Ephemeris (Astrodienst), a csomagban kapott C forrásból fordítva. A belső verziószám
2.10.03, a git tagv2.10.3bfinal. A bolygópozíciók ívmásodpercnél pontosabbak. - A Rust-kötést automata tesztek vetik össze a hivatalos
swetestprogram eredményeivel: bolygók, sebességek, házcsúcsok, Vertex, Delta T, sarkvidéki visszaesés. - Az adatfájlok 1800–2399-et fedik le. Ezen kívül a motor a pontatlanabb Moshier-efemeriszre vált, a Chiron és a kisbolygók kimaradnak, és a válasz
warningsmezőjében figyelmeztetés jelenik meg. - A sarkkörökön túl a Placidus/Koch/Topocentrikus házrendszer nem értelmezhető; ilyenkor Porphyry-re vált, és figyelmeztetést ad.
- A motor az
astro_engine::Ephemeristrait mögött van. Egy licenctiszta motor (pl. JPL DE440 + saját Rust kód) a trait implementálásával beköthető, a horoszkóplogika módosítása nélkül.
Licencek
- Swiss Ephemeris: AGPL-3.0 vagy fizetős Swiss Ephemeris Professional License. Ha a szolgáltatást mások a hálózaton keresztül használják, AGPL alatt a teljes forrást elérhetővé kell tenni, különben kereskedelmi licenc kell. Emiatt a workspace licence jelenleg
AGPL-3.0-or-later. - GeoNames: CC BY 4.0. A forrásmegjelölés benne van az API válaszában (
meta.data_sources). - IANA tzdb: public domain.