Add core engine: tarot + astrology reading generator with CLI and i18n

Plain-C, dependency-free engine that produces a personalized daily Celtic Cross tarot spread and natal-chart/transit astrology reading, plus a standalone CLI (dist/deck-engine) and run.sh wrapper. Includes English/German output via a simple key=value translation format, and docs/diagrams describing the architecture and I/O.
2026-07-04 06:49:18 +02:00
commit e4ea31270f
59 changed files with 17134 additions and 0 deletions
@@ -0,0 +1,54 @@
+To calculate daily celestial events for astrology software, you must integrate an ephemeris engine that computes precise planetary coordinates and then apply astrological algorithms to interpret those positions as transits, aspects, and house placements. [1, 2] 
+## 1. Choose a Calculation Engine
+The industry standard for professional astrology software is the [Swiss Ephemeris](https://roxyapi.com/blogs/swiss-ephemeris-explained-developers) (SE), a C library from Astrodienst AG. [2, 3] 
+
+* Accuracy: It provides sub-milliarcsecond precision based on NASA JPL data.
+* Availability: It is available as a C library, but popular wrappers exist for Python ([Pyswisseph](https://vedika.io/blog/astrology-software-development-guide)), Java, and Node.js.
+* Licensing: It uses an AGPL license, meaning you must open-source your code unless you purchase a commercial license. [2, 3, 4, 5] 
+
+## 2. Implement the Daily Logic Loop
+Your software should follow a structured computational sequence to describe daily events:
+
+   1. Coordinate Conversion: Collect user location/time and convert it to Universal Time (UTC). [1, 6, 7] 
+   2. Ephemeris Query: Call the engine to get the longitude and latitude of the Sun, Moon, and planets. [3, 8] 
+   3. House Calculation: Use your chosen system (e.g., Placidus, Koch, or Whole Sign) to determine house cusps based on the time and location. [9, 10] 
+   4. Aspect Detection: Calculate the angular distances between planets (e.g., a 120° angle is a Trine) and check if they fall within a specific "orb" of influence (typically 1° to 10°). [1, 11, 12, 13] 
+   5. Transit Analysis: Compare current planetary positions to a user's Natal Chart to generate personalized daily insights. [9, 14] 
+
+## 3. Key Development Tools
+
+| Category [1, 2, 11, 15, 16] | Recommended Tools |
+|---|---|
+| Libraries | Kerykeion[](https://kerykeion.net/) (Python), Stellium[](https://github.com/katelouie/stellium) (Python), Astronomy Engine[](https://github.com/cosinekitty/astronomy) (JS/C++/Python). |
+| APIs | Vedika API[](https://vedika.io/blog/how-to-build-astrology-api) or Roxy Ephemeris for managed calculations without local engine hosting. |
+| Automation | Use cron jobs (e.g., 0 0 * * *) to refresh planetary positions and daily forecasts every 24 hours. |
+
+## 4. Important Calculations for Daily Content
+
+* Ingresses: Tracking when a planet enters a new zodiac sign.
+* Stations & Retrogrades: Identifying when a planet appears to slow down (stationary) or move backward.
+* Planetary Hours: Dividing day and night into 12 "unequal hours" each, assigned to traditional planets.
+* Lunar Cycles: Calculating the Moon's phase (New, Full, etc.) and its current sign (changes every ~2.5 days). [9, 17, 18, 19, 20] 
+
+If you are building the backend now, would you like to see a Python code snippet for a basic aspect calculation, or do you need a breakdown of different house systems?
+
+[1] [https://dev.to](https://dev.to/kamal_deeppareek_f5bb5d8/how-to-integrate-planetary-data-into-your-astrology-app-2cgo)
+[2] [https://roxyapi.com](https://roxyapi.com/blogs/swiss-ephemeris-explained-developers)
+[3] [https://dev.to](https://dev.to/kamal_deeppareek_f5bb5d8/how-to-integrate-planetary-data-into-your-astrology-app-2cgo)
+[4] [https://vedika.io](https://vedika.io/blog/astrology-software-development-guide)
+[5] [https://en.wikipedia.org](https://en.wikipedia.org/wiki/Astrology_software)
+[6] [https://dev.to](https://dev.to/kamal_deeppareek_f5bb5d8/how-to-integrate-planetary-data-into-your-astrology-app-2cgo)
+[7] [https://kerykeion.net](https://kerykeion.net/astrologer-api/guides/astrology-software-development)
+[8] [https://www.quora.com](https://www.quora.com/Does-astrology-software-enter-the-full-ephemeris-in-the-software-to-calculate-planetary-positions-and-the-ascendant-or-are-there-some-formulae-to-calculate-the-same)
+[9] [https://www.youtube.com](https://www.youtube.com/watch?v=TnoG0DR9SMY)
+[10] [https://www.reddit.com](https://www.reddit.com/r/Advancedastrology/comments/1rss61c/is_there_an_astronomical_algorithms_for_astrology/)
+[11] https://kerykeion.net
+[12] [https://algocademy.com](https://algocademy.com/blog/the-unexpected-connection-between-coding-and-astrology-unlocking-the-secrets-of-the-digital-cosmos/)
+[13] [https://support.astrograph.com](https://support.astrograph.com/support/solutions/articles/66000476614-desktop-manual-timepassages)
+[14] [https://www.molecularcloud.org](https://www.molecularcloud.org/p/how-do-you-create-a-real-time-astrology-prediction-app)
+[15] [https://github.com](https://github.com/katelouie/stellium)
+[16] [https://vedika.io](https://vedika.io/blog/how-to-build-astrology-api)
+[17] [https://www.youtube.com](https://www.youtube.com/watch?v=yfO_v55XW_0)
+[18] [https://kerykeion.net](https://kerykeion.net/content/learn-astrology/guide-timing-techniques)
+[19] [https://play.google.com](https://play.google.com/store/apps/details?id=info.thereisonlywe.planetarytimes)
+[20] [https://www.llewellyn.com](https://www.llewellyn.com/journal/article/534)
@@ -0,0 +1,60 @@
+The term "Celtic Tarot" most often refers to the Celtic Cross spread, which is the most widely used 10-card layout in divination. It also describes a category of tarot decks that replace traditional symbols (like the Hierophant) with Celtic archetypes (like the Druid). [1, 2, 3, 4, 5] 
+## The Celtic Cross Spread
+The layout is divided into two parts: the Cross (six cards on the left) representing current energies, and the Staff (four cards on the right) representing external influences and the final path. [6, 7, 8] 
+
+[The Celtic Cross Tarot Spread - A Classic 10 Card Tarot ...](https://labyrinthos.co/blogs/learn-tarot-with-labyrinthos-academy/the-celtic-cross-tarot-spread-exploring-the-classic-10-card-tarot-spread)
+[Breaking Down the Celtic Cross - Lesson 1: Laying it out](https://www.thetarotlady.com/breaking-celtic-cross-lesson-1-laying/)
+[How to Read a Celtic Cross Tarot Spread and Gain Deep ...](https://astrostyle.com/tarot/how-to-read-the-celtic-cross-tarot-spread/)
+[How to Read the Celtic Cross Tarot Spread | The Pagan Grimoire](https://www.pagangrimoire.com/how-to-read-the-celtic-cross-tarot-spread/)
+[The Celtic Cross Tarot Spread (My Favorite) - Tarot Spreads ...](https://forum.thetarot.guru/t/the-celtic-cross-tarot-spread-my-favorite/294)
+[How to Read The Celtic Cross Spread – Truly Teach Me Tarot](https://teachmetarot.com/celtic-cross-spread/how-to-read-the-celtic-cross-spread/)
+[Celtic Cross Tarot Spread Tutorial (explaining the positions ...](https://www.youtube.com/watch?v=ma30RYGonws)
+[Celtic Cross Tarot: Meaning, Spread Positions, and How to ...](https://www.theirishjewelrycompany.com/blog/post/celtic-cross-tarot-meaning-spread-positions)
+
+| Position [3, 6, 7, 9, 10, 11, 12] | Meaning | Key Focus |
+|---|---|---|
+| 1. The Present | Heart of the matter | Current situation or state of mind |
+| 2. The Challenge | What "crosses" you | Immediate obstacles or supporting forces |
+| 3. The Foundation | Distant past | Root causes or subconscious influences |
+| 4. Recent Past | Passing events | Influences that led to the present |
+| 5. Higher Power | Conscious goals | Best possible outcome or aspirations |
+| 6. Near Future | Next steps | Immediate events approaching soon |
+| 7. The Self | Your approach | Your current internal perspective |
+| 8. External | Your environment | Influences from others and your surroundings |
+| 9. Hopes/Fears | Inner state | Deepest anxieties or desired resolutions |
+| 10. Final Outcome | Likely result | Long-term result based on current energy |
+
+## Popular Celtic-Themed Decks
+If you are looking for a deck inspired by Celtic mythology rather than just the spread, several highly-regarded options exist:
+
+* [DruidCraft Tarot](https://druidry.org/druid-way/other-paths/wicca-druidcraft/druidcraft-tarot): Combines Wiccan and Druidic traditions; noted for its rich, earthy artwork.
+* Celtic Spirit Tarot: An expanded 92-card deck that incorporates Celtic shamanism and an extra "Spirit" suit.
+* Universal Celtic Tarot: A [Lo Scarabeo](https://www.loscarabeo.com/en) deck that weaves traditional tarot with myths of gods like Lugh and Brigid.
+* Celtic Elemental Tarot: Renames traditional suits to Earth, Air, Water, and Fire, and features figures like King Arthur. [13, 14, 15, 16, 17] 
+
+## Origins and History
+Contrary to popular belief, the ancient Celts did not use tarot; they likely used Ogham or runes for divination. The "Celtic Cross" spread was popularized (and likely invented) by [A.E. Waite](https://en.wikipedia.org/wiki/A._E._Waite) in 1911 in his book [The Pictorial Key to the Tarot](https://www.amazon.de/Pictorial-Key-Tarot-Divination-Illustrated/dp/1614273030). He marketed it as an "ancient" method to give it credibility during the occult revival of that era. [18, 19, 20, 21, 22] 
+Would you like a step-by-step guide on how to perform the Celtic Cross spread yourself, or are you looking for recommendations for a specific Celtic-themed deck?
+
+[1] [https://www.youtube.com](https://www.youtube.com/shorts/zK6d7glfWN8)
+[2] [https://www.learntarot.com](https://www.learntarot.com/ccross.htm)
+[3] [https://www.theirishjewelrycompany.com](https://www.theirishjewelrycompany.com/blog/post/celtic-cross-tarot-meaning-spread-positions)
+[4] [https://jackofwandstarot.wordpress.com](https://jackofwandstarot.wordpress.com/2018/03/07/a-review-of-the-celtic-tarot/)
+[5] [https://www.youtube.com](https://www.youtube.com/watch?v=_-nvrQkfCF4)
+[6] [https://celticstudio.shop](https://celticstudio.shop/blogs/article/celtic-cross-in-tarot-meaning-and-spread)
+[7] [https://elvitarot.com](https://elvitarot.com/blog/celtic-cross-tarot-spread/)
+[8] [https://science.howstuffworks.com](https://science.howstuffworks.com/science-vs-myth/extrasensory-perceptions/celtic-cross-spread.htm)
+[9] [https://www.thetarotlady.com](https://www.thetarotlady.com/breaking-celtic-cross-lesson-1-laying/)
+[10] [https://www.youtube.com](https://www.youtube.com/watch?v=Za-0683VWYg&t=381)
+[11] [https://www.thetarotlady.com](https://www.thetarotlady.com/breaking-celtic-cross-lesson-1-laying/)
+[12] [https://forum.thetarot.guru](https://forum.thetarot.guru/t/the-celtic-cross-tarot-spread-my-favorite/294)
+[13] [https://www.amazon.de](https://www.amazon.de/-/en/Celtic-Tarot-Lo-Scarabeo/dp/0738700134)
+[14] [https://www.reddit.com](https://www.reddit.com/r/tarot/comments/184p9as/can_anyone_recommend_tarot_or_oracle_decks_with_a/)
+[15] [https://www.youtube.com](https://www.youtube.com/watch?v=OVO05l9i8AA&t=161)
+[16] [https://www.youtube.com](https://www.youtube.com/watch?v=9GJQFtDXpQc&t=15)
+[17] [https://www.youtube.com](https://www.youtube.com/watch?v=TsZYRyQabdk&t=2)
+[18] [https://www.quora.com](https://www.quora.com/Did-Celtics-Vikings-and-Normans-do-tarot-cards)
+[19] [https://www.occult.live](https://www.occult.live/index.php?title=Celtic_Cross&mobileaction=toggle_view_desktop)
+[20] [https://tarotandkitchenwitchery.com](https://tarotandkitchenwitchery.com/celtic-cross-tarot-spread/)
+[21] [https://www.amazon.com.au](https://www.amazon.com.au/Ogham-Divining-25-Card-192-Page-Guidebook/dp/1578638909)
+[22] [https://www.solacely.co](https://www.solacely.co/blogs/astrology-and-crystals/celtic-rune-symbols)
@@ -0,0 +1 @@
+https://www.learntarot.com/cards.htm