← Back to blog
AiAbout 6 min read

A Chinese Astrology Repo Published 20 Billion Characters. The Engine Is MIT. The Sentences Are Not.

Published Nov 8, 2026
A Chinese Astrology Repo Published 20 Billion Characters. The Engine Is MIT. The Sentences Are Not.

The fourth fastest-growing repository on GitHub this week is a TypeScript project that calculates Chinese astrological charts. It added 4,906 stars in seven days, which puts it above most model releases and below only a handful of agent tools.

The project is called ziwei-doushu, after the 紫微斗数 system it implements. It is built on the teaching system of Ni Haixia, a late Chinese medicine practitioner whose lecture series on the subject runs fourteen sessions. The repository contains a complete charting engine, the classical texts in their public-domain originals, and a dataset that is the reason anyone should look at this repository at all.

What is actually in the dataset

Version 4.0, released on October 15, contains 674,976 charts. Each chart is expanded across thirteen interpretive dimensions, which produces 8,774,688 interpretation entries. The body text comes to roughly 20.4 billion characters, or 56.6 gigabytes decompressed, or 161 megabytes compressed and split into 77 files by year.

Blank accordion-folded paper in a long zigzag across a dark walnut table.

The chart count is exhaustive: every real calendar date from 1950 to 2026, crossed with twelve traditional two-hour periods and both genders. The dataset ships with a per-chart average of about 30,000 characters of interpretation.

Before publishing, the maintainers decompressed all 77 files and compared them byte by byte against the source data. That is the kind of QA note that tells you the person shipping it has been burned before.

The previous version, 3.0, covered 518,400 charts from 1924 to 1983 and decompressed to 33.1 gigabytes. Version 4.0 grew the coverage by seventeen years, the chart count by 30 percent, and the decompressed size by 71 percent, because the interpretation text got longer per chart.

The engine is the part that would survive a rewrite

The charting core sits in `lib/ziwei/`, and the feature list reads like a list of arguments that practitioners have been having for decades.

True solar time correction adjusts for longitude difference and the equation of time, so a birth recorded in western China does not get shifted a full two-hour period by the clock. China's 1986 to 1991 daylight saving windows are detected, but deliberately not subtracted: the app flags the period and lets the user confirm the clock reading before converting. Leap months support four separate conventions, configurable rather than hardcoded to one school. The late-zi hour rule switches the day at 23:00, and the switch is configurable. Star brightness is graded across seven levels with three coarser levels kept for display fallback, and the brightness school itself is a toggle, because mainstream charting software disagrees with each other.

There are also the four transformations and flying star system, twelve seasonal spirits split between the natal layer and the annual layer, and a pattern library of more than 1,100 rules covering classics like 紫府同宫 and 七杀朝斗.

This is not decoration. In a system where schools disagree about brightness assignments, hardcoding one interpretation is a product decision disguised as an implementation detail. Making them switches is what turns a personal tool into something another practitioner will accept.

Getting it running

The stack is Next.js 16 with the App Router, TypeScript, Tailwind, Framer Motion, and the iztro and lunar-javascript libraries underneath the charting logic.

``` git clone https://github.com/Renhuai123/ziwei-doushu.git cd ziwei-doushu npm install cp .env.example .env.local npm run dev ```

Verification is a single command. `npm test` runs a regression suite across 768 charts covering the core rules, daylight saving boundaries, the start of spring boundary, sample consistency, hour index edges, date validity and double transformations in the same palace. The same suite runs in GitHub Actions on every push.

Reading a chart needs no API key and no backend. The engine runs in the browser.

The boundary is drawn with unusual precision

Here is where this repository differs from most open-source launches. The maintainers published a table of what is not included, with line counts to prove it.

| Component | Open demo | Commercial product | |---|---|---| | Chart page | 75 lines | 1,227 lines | | Interpretation panel | 467 lines | 5,088 lines | | Chart grid | 285 lines | 1,334 lines | | Palace cell | 201 lines | 1,192 lines | | Compatibility page | 368 lines | 1,937 lines |

The interpretation formula library, which is the thing that actually tells a user what their chart means, is not open. In the repository, `db-analysis.ts` is a placeholder. The AI interpretation prompts are not open. The backend routes are not open, and the README is blunt that configuring an API key will not make `/api/interpret` work, because the endpoint does not exist in the open version. The user system, the payment flow, the anti-abuse layer and the deployment configuration are all absent.

What is open: the engine, the classical texts, an SEO knowledge graph of fourteen stars across twelve palaces, the demo interface, and the datasets.

The licensing follows the same logic, in four parts. Code is MIT. Datasets are CC BY 4.0, commercial use allowed with attribution. The classical texts are public domain. The 1,848 transcribed quotes from the lecture series are CC BY-NC-SA 4.0, meaning non-commercial only, and the dataset licence explicitly excludes them.

That last clause is the one to notice. Twenty billion characters of generated interpretation are free to use commercially, as long as you attribute. The 1,848 source quotes they were derived from are not.

Why this is interesting beyond astrology

Three things about this repository generalize.

The first is the shape of the moat. A solo developer built a charting engine, then a knowledge base, then a dataset, and open-sourced the parts that are expensive to rebuild and cheap to copy, while keeping the parts that are cheap to write and hard to copy: the interpretive text, the prompt, the funnel. That is a more sophisticated reading of "open source" than most funded startups manage.

The second is the dataset as a product. Generating 8.7 million interpretation entries is a brute-force exercise in coverage: every date, every hour, both genders, thirteen dimensions. It is useful for evaluation, for fine-tuning, for building a competing product, and for anyone who wants to check whether two interpretations contradict each other across a full date range. Publishing it costs almost nothing to distribute and buys a kind of credibility that a landing page cannot.

The third is distribution. The README ends with an invitation to say hello on Xiaohongshu, Douyin and Xianyu, the Chinese resale app. The funnel runs from a GitHub repository to a hosted site to a social account, in that order, and the repository is doing the job a content marketing budget usually does.

The maintainers describe the repository as an "open snapshot" rather than a maintained product, warn that issues may get slow replies, and ask that anyone changing charting conventions bring a citation. For a project with 16,700 stars and a 56-gigabyte dataset, that is a fair description of the deal.

If you want the engine, take it. If you want the sentences, the sentences are the business.

Related articles