← Back to blog
GeneralAbout 6 min read

A 1,100-Rule Astrology Engine Is Out-Engineering Most AI Products

Published Nov 8, 2026
A 1,100-Rule Astrology Engine Is Out-Engineering Most AI Products

A TypeScript repository for Chinese astrological chart calculation has 16,868 stars on GitHub this week. That is more than most developer tools get in a lifetime, for a subject that most Western engineers would file under "not software."

The interesting part is not the subject. It is that the repository is a better piece of engineering than a lot of what ships under the label "AI product."

ziwei-doushu is an open-source engine for 紫微斗数 — Purple Star Astrology — built on the system taught by 倪海厦 in his 天纪 lectures. Charts are computed entirely in the browser. There is no API key, no model, no inference. It is arithmetic, lookup tables, and 1,100 lines of pattern rules.

And it comes with 768 regression charts.

What it actually computes

If you do not know the domain, the README's capability table doubles as a list of the ways this kind of calculation goes wrong.

True solar time correction. A birth time recorded on a clock is not the solar time at that location. The engine corrects for longitude difference plus the equation of time, so that a chart cast in the east of the country does not land one double-hour off. This is the astrological equivalent of a timezone bug, and it is the first thing that breaks in naive implementations.

Chinese daylight saving, 1986 to 1991. The country observed DST for six years and then stopped. The engine detects the interval but deliberately does not subtract the hour automatically — the README is explicit that clock readings are confirmed by the user and then converted through a separate clock-adjust.ts. That is a correct instinct. Silently adjusting a user's input is how you produce charts that are confidently wrong.

Four conventions for leap months. Schools disagree on whether a leap month belongs to the preceding month, the following month, splits by day, or counts as its own. The engine makes it a setting instead of picking a side. Same for star brightness, where different traditions — and different versions of the same commercial software, use different scales. Seven levels are supported, with a coarser three-level classification for display fallback.

Late zi hour day switching. 23:00 to 23:59 is treated as the next day; 00:00 to 00:59 as the current day. If a birth location is provided, the judgement is made on true solar time so the two rules stay consistent.

On top of that sit the four transformations and flying stars, twelve spirit-and-killings placements that shift between natal and annual layers, and a pattern library of more than 1,100 rules — 紫府同宫, 日月并明, 七杀朝斗 and the rest.

A carved wooden printing block and a worn ink brush on coarse paper

The tests are the argument

Anyone can claim their chart engine is correct. This one publishes a test suite that runs on every push and pull request, and the list of what it checks is the most informative part of the repository:

768 charts against the system's iron rules. Daylight saving intervals. The 立春 boundary, where the year changes in this calendar and where almost every implementation has an off-by-one. 红鸾 and 天喜 placement. Consistency of the hour index across sample charts. Hour index boundary conditions. Date validity. The case where two transformations land in the same palace.

That is not a marketing list. That is a list written by someone who was bitten by each item in turn. The 立春 boundary alone will break a naive implementation every single year for anyone born in the first week of February.

Installing it

Three commands:

git clone https://github.com/Renhuai123/ziwei-doushu.git
cd ziwei-doushu
npm install

Optionally cp .env.example .env.local, then npm run dev. Verification is npm run typecheck for a full TypeScript pass and npm test for the chart engine's regression suite.

No API key is required for casting or displaying a chart, and none is required for the compatibility chart. Everything runs client-side, which is the right call for something built from a birth date and a birth location.

The boundary the author drew, and why it is the most honest thing in the README

The open-source version does not include the backend API routes. Chart casting, chart display, and compatibility casting are all local. But the AI interpretation endpoint — /api/interpret — and the compatibility analysis endpoint are not implemented.

Without them, the interface says, plainly, that the open-source version does not include that endpoint. And the README adds a line that resolves an issue people kept filing: configuring an API key will not make those features work. Issue #30 exists because users assumed otherwise.

That is an unusual decision. The easy move would be to ship a stub that calls a model and produces plausible-sounding commentary. Instead the repository is a calculator that refuses to pretend it is an oracle. Given how much of this subject's online presence is confident nonsense, a tool that stops at the edge of what it can compute is worth noticing.

The naming, and why it reads like a library

The code is organized around the way the discipline is actually taught, and that is why it is readable.

lib/ziwei/algorithm.ts holds the casting sequence: place the life palace, determine the five-element局, place the fourteen major stars, place the auxiliary stars, lay out the decade and annual cycles. constants.ts holds the stems, branches, and star lists. sihua.ts holds the four transformations — 禄, 权, 科, 忌, including the flying-star self-transformation cases. Then separate modules for the pattern library and the brightness tables.

If you know the subject, that mapping is obvious. If you do not, it is still legible: constants, then arithmetic, then rules, then interpretation-adjacent data. The domain is unfamiliar and the structure is not, which is what good software looks like when it is built by someone who understands the thing rather than the trend.

The TypeScript choice matters too. Charts are a tree of palaces with stars in each, transformed by rules that reference each other. A type system that can express "a palace contains a list of stars, each with a brightness level from a fixed set" catches a whole class of bug at compile time, and the repository runs a full typecheck before anything else. For a domain with this many enumerated values, that is not decoration.

Why an AI blog is writing about an astrology engine

Because it is the clean counterexample to how most AI products are built right now.

Here is a system where every output is deterministic, every rule is attributable to a named tradition, every ambiguous convention is a configuration switch rather than an opinion, and correctness is enforced by 768 regression cases. Ask it a question twice and you get the same answer. Nothing is hallucinated, because nothing is generated.

Then there is the part it explicitly will not do: interpret. The interpretation layer — the part that requires judgement, and where different practitioners will disagree — is left to the user or to a separately implemented endpoint.

Most teams building with language models would benefit from copying that split. Compute what can be computed, exactly, and be explicit about where interpretation begins. The alternative is a system that sounds authoritative about the difference between the two, which is precisely the failure mode this repository was designed to avoid.

The code is MIT. The dataset is CC BY 4.0. The classical texts are public domain. The lecturer's own words are licensed non-commercially, and the README says so. All of that is documented, which is more than most projects manage about far less contentious material.

You do not have to believe in the subject to learn something from the engineering. That is usually the mark of a well-made thing.

Related articles