ml
121 lines
5.2 KiB
Markdown
121 lines
5.2 KiB
Markdown
<p align="center">
|
|
<img src="res/logo.png" width="290" 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-engine.sh, run-interpreter.sh, and
|
|
the user.properties template.
|
|
dist/ Build output (gitignored) — see below.
|
|
interpreter/ Separate module + binary (dist/interpreter-cli):
|
|
scores how significant a day's transits are,
|
|
reading deck-engine's --format json output
|
|
(see CLAUDE.md).
|
|
docs/ Architecture/dataflow diagrams, input/output format reference.
|
|
Makefile Single root Makefile, builds both engine/ and interpreter/.
|
|
```
|
|
|
|
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
|
|
make # -> dist/deck-engine, dist/interpreter-cli, dist/img/, dist/i18n/,
|
|
# dist/run-engine.sh, dist/run-interpreter.sh, dist/user.properties
|
|
make test # builds and runs engine/tests/smoke_test.c and interpreter/tests/*_test.c
|
|
```
|
|
|
|
Requires only a C99 compiler and `make` — no other dependencies.
|
|
|
|
## Running
|
|
|
|
**Daily use**, via `dist/run-engine.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-engine.sh # text output, language from user.properties (default en)
|
|
dist/run-engine.sh html # HTML report with card art, open in a browser
|
|
dist/run-engine.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|json] [--lang en|de]
|
|
```
|
|
|
|
**Interpreter** (`interpreter/`, built by the same root `make`):
|
|
scores how significant a day's transits are, reading `deck-engine`'s
|
|
`--format json` output — the two binaries compose over that JSON, they're
|
|
never linked together. `dist/run-interpreter.sh` is the daily-use
|
|
equivalent of `run-engine.sh` (same OS clock + `user.properties` inputs),
|
|
piping straight into `interpreter-cli`:
|
|
|
|
```bash
|
|
dist/deck-engine ... --format json | dist/interpreter-cli
|
|
# or, for daily use:
|
|
dist/run-interpreter.sh
|
|
```
|
|
|
|
## License
|
|
|
|
The engine source code in this repository (`engine/src/`, `engine/scripts/`)
|
|
and the root `Makefile` are 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.
|