Renhuai123/ziwei-doushu

The problem

Zi Wei Dou Shu charting is one of those domains where every practitioner's software is a black box: the placement rules, brightness tables and interpretation texts live inside closed products, so you cannot verify a chart by hand or reuse the texts in your own tool. Anyone building a Chinese astrology app ends up reimplementing the calendar, true-solar-time and four-transformation logic from scratch, then writing the reading text themselves. This project publishes both halves: the charting engine as TypeScript source, and a bulk interpretation corpus generated deterministically from it.

What's different

Most comparable software is either a desktop or web app whose output you can only look at, or scattered reference material with no executable code. Here the engine is ordinary TypeScript you can read and test, and the repo ships a much larger artifact than the code: a dataset of roughly 675k charts across 13 analysis dimensions, generated from 1950–2026 real dates, released as zstd-compressed JSON Lines split by year so you can pull only what you need. Generation is rule-based, not AI, so the same input always produces the same output — unusual in a space now dominated by LLM-generated readings. It also documents where its own limits are, e.g. the explicit note that the six-relations columns are weak and should be treated as reference.

Who it's for

Developers building astrology products, researchers doing quantitative work on chart structures, and people who want training or RAG corpora for Chinese-language domain text. It is not for practitioners who only want a ready-made reading app — the shipped UI is described as a demo, not the production site. Nor is it useful if you need a different lineage: the content is tied to one teacher's system, and readings tied to other schools' interpretation styles will not match.

Cost of adoption

Code is MIT, data is CC BY 4.0 with attribution — commercially usable. The full corpus is about 56 GB uncompressed and needs zstd -d --long=27; that is the real cost, not the install. Quoted teacher transcript excerpts are outside the data license and carry non-commercial terms, so anything built on those quotations needs separate handling. Engine source requires Node and Next.js for the demo. Maturity signals are mixed: the repo is only months old, tests and CI were added recently, and there are known data caveats (a prior version shipped impossible dates, and brightness defaults changed after v4.0, so some sentences drift from the engine).

Verdict

This is not an established library with a long track record; it is a young project that arrived with an unusually large data release and a rapid star spike — 7,225 stars on a 176-day-old repo, +2,556 in a month. The open code is modest in scope; the dataset is the actual product. Treat it as a corpus and a reference implementation, verify a few charts against known references before shipping, and check the license boundaries around the quoted material. The candor about limitations is a good sign, but the maintenance history is too short to assume stability.