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.
This commit is contained in:
ml
@@ -0,0 +1,102 @@
|
||||
<p align="center">
|
||||
<img src="res/logo.png" width="200" alt="Deck in a Dash logo">
|
||||
</p>
|
||||
|
||||
# Deck in a Dash
|
||||
|
||||
A Pebble smartwatch app that produces a daily personalized tarot (Celtic
|
||||
Cross) and astrology (natal chart + transits) reading.
|
||||
|
||||
**Status:** only the core engine exists so far — a plain-C, dependency-free
|
||||
library and standalone CLI (`dist/deck-engine`) that computes a full
|
||||
reading without needing a Pebble device, emulator, or SDK. The watchapp
|
||||
itself hasn't been built yet; the engine is designed so it can be linked
|
||||
into it later without rework.
|
||||
|
||||
## What it computes
|
||||
|
||||
- **Astrology**: a personalized natal chart (Sun through Pluto, plus the
|
||||
Ascendant and whole-sign houses) from a birth date, time, and location,
|
||||
and the day's transits — including moon phase and aspects — against
|
||||
that chart.
|
||||
- **Tarot**: a 10-card Celtic Cross spread, drawn from the 22 Major
|
||||
Arcana, with upright/reversed orientation per card. The full spread is
|
||||
deterministic: the same seed string always produces the same cards, in
|
||||
the same positions, with the same orientations. Card meanings and
|
||||
spread positions are sourced from A. E. Waite's *The Pictorial Key to
|
||||
the Tarot* (1911, public domain), in his own original drawing order.
|
||||
|
||||
Readings are available in **English and German** (`--lang en`/`--lang
|
||||
de`, or `lang=` in `user.properties`); adding another language is just
|
||||
dropping a translated `key=value` file into `engine/i18n/` — see
|
||||
[`docs/input-output-format.md`](docs/input-output-format.md).
|
||||
|
||||
## Repository layout
|
||||
|
||||
```
|
||||
res/ Tarot card art (22 RWS Major Arcana), the
|
||||
Waite PDF, logo, research notes.
|
||||
engine/
|
||||
third_party/astronomy/ Vendored cosinekitty/astronomy C library (MIT).
|
||||
src/ Engine source (rng, tarot, astro, i18n, reading, CLI).
|
||||
i18n/ Translation files (en.lang, de.lang, ...).
|
||||
tests/smoke_test.c Determinism, ephemeris, and i18n regression checks.
|
||||
scripts/ run.sh and the user.properties template.
|
||||
Makefile
|
||||
dist/ Build output (gitignored) — see below.
|
||||
docs/ Architecture/dataflow diagrams, input/output format reference.
|
||||
```
|
||||
|
||||
See [`CLAUDE.md`](CLAUDE.md) for the detailed architecture and the sharp
|
||||
edges worth knowing before changing the engine, or the
|
||||
[`docs/`](docs/) directory for diagrams
|
||||
([`docs/architecture.md`](docs/architecture.md)) and the full CLI/file/
|
||||
struct format reference
|
||||
([`docs/input-output-format.md`](docs/input-output-format.md)).
|
||||
|
||||
## Building
|
||||
|
||||
```bash
|
||||
cd engine
|
||||
make # -> dist/deck-engine, dist/img/, dist/i18n/, dist/run.sh, dist/user.properties
|
||||
make test # builds and runs engine/tests/smoke_test.c
|
||||
```
|
||||
|
||||
Requires only a C99 compiler and `make` — no other dependencies.
|
||||
|
||||
## Running
|
||||
|
||||
**Daily use**, via `dist/run.sh`: pulls today's date and the current UTC
|
||||
time from the OS clock (used as the tarot seed and the transit moment)
|
||||
and reads your birth data from `dist/user.properties`. Edit that file
|
||||
first — it's seeded once from a placeholder template and is never
|
||||
overwritten by later builds:
|
||||
|
||||
```bash
|
||||
dist/run.sh # text output, language from user.properties (default en)
|
||||
dist/run.sh html # HTML report with card art, open in a browser
|
||||
dist/run.sh html de # override the language for this run
|
||||
```
|
||||
|
||||
**Direct CLI**, with every input explicit:
|
||||
|
||||
```bash
|
||||
dist/deck-engine --seed "2026-07-03" \
|
||||
--birth-date 1990-05-14 --birth-time 14:32 --birth-utc-offset 2 \
|
||||
--birth-lat 52.5200 --birth-lon 13.4050 \
|
||||
[--date YYYY-MM-DDTHH:MM] [--format text|html] [--lang en|de]
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
The engine source code in this repository (`engine/src/`, `engine/scripts/`,
|
||||
`engine/Makefile`) is released under the **MIT License** — see
|
||||
[`LICENSE`](LICENSE).
|
||||
|
||||
`engine/third_party/astronomy/` is vendored from
|
||||
[cosinekitty/astronomy](https://github.com/cosinekitty/astronomy) (MIT,
|
||||
unmodified) — see its `VENDORED.md` for the pinned commit.
|
||||
|
||||
Card and spread text in `engine/src/tarot_data.c` is condensed from A. E.
|
||||
Waite's *The Pictorial Key to the Tarot* (1911), which is in the public
|
||||
domain.
|
||||
Reference in New Issue
Block a user