Open-Source Zi Wei Dou Shu Charting Engine: A TypeScript Implementation with 6,552 Stars

An Open-Source Project That Went Viral Unexpectedly

On GitHub's daily trending list, a TypeScript project called Renhuai123/ziwei-doushu has been quietly climbing. It's not another AI framework or developer tool, but a Zi Wei Dou Shu (Purple Star Astrology) charting engine—built on Ni Haixia's Tian Ji system, it includes a complete charting algorithm, the Four Transformations (Si Hua) system, a pattern knowledge base, and original classical texts. As of the material record, the project has garnered 6,552 stars and 1,345 forks, with 547 new stars in a single day.

These numbers aren't top-tier among technical projects, but given the niche nature of its subject matter, they're enough to illustrate a phenomenon: the traditional divination field is undergoing a digital reconstruction driven by the open-source community.

Where Are the Technical Challenges in Zi Wei Dou Shu Charting?

Zi Wei Dou Shu may look like "fortune-telling," but its charting process is essentially a set of rule-intensive deterministic calculations. Unlike BaZi, which relies on the linear progression of heavenly stems and earthly branches, Zi Wei Dou Shu must handle multiple variables simultaneously:

• Star placement: Assigning palace positions to over a hundred stars—the fourteen major stars, six auspicious and six inauspicious stars, and the Four Transformation stars—each with its own placement rules
• Four Transformations system: Superposition and priority determination of birth-year Si Hua, major-period Si Hua, and annual Si Hua
• Pattern identification: Automatic recognition of dozens of classical patterns (such as "Zi Fu Tong Gong" and "Ri Yue Fan Bei")
• Calendar conversion: Astronomical and calendrical issues such as the lunar calendar, leap months, and true solar time correction

These rules are scattered across classical texts like Zi Wei Dou Shu Quan Shu and Gu Sui Fu, often expressed ambiguously. The distinguishing feature of Ni Haixia's Tian Ji system is its systematic organization of traditional rules, and the value of this project lies precisely in making this system codified and verifiable.

Implementing it in TypeScript means the type system can explicitly constrain the data structures of stars, palaces, and Four Transformations, reducing the error rate in rule implementation. For application scenarios requiring precise calculation, this offers greater engineering reliability than scripting-language solutions.

The Four Transformations system is the most dynamic part of Zi Wei Dou Shu and the main source of charting complexity. The Four Transformations refer to Hua Lu, Hua Quan, Hua Ke, and Hua Ji—four energy transformations corresponding respectively to wealth, power, reputation, and obstruction. They are triggered by heavenly stems: each stem causes fixed transformations in four stars—for example, the Jia stem causes Lian Zhen to transform to Lu, Po Jun to Quan, Wu Qu to Ke, and Tai Yang to Ji. The difficulty lies in multi-layer superposition—birth-year Si Hua, determined by the heavenly stem of the birth year, forms the foundational tone of the chart; major-period Si Hua, determined by the heavenly stem of the decade's palace, represents the theme of a phase; annual Si Hua, determined by the annual heavenly stem, reflects yearly events. When all three coexist, priority and interaction must be determined—for instance, how to interpret birth-year Hua Lu meeting major-period Hua Ji—and different schools have different opinions. Code implementation must explicitly define superposition rules and conflict-resolution strategies; otherwise, results cannot be reproduced. This is one reason the project chose an explicit system as its baseline.

True solar time correction is a critical step often overlooked before charting that nonetheless affects results. Zi Wei Dou Shu determines the life palace by birth hour, and traditional hours are divided according to local mean solar time, whereas birth times recorded by modern people are mostly Beijing Time (UTC+8 standard time). If the birthplace is not near 120°E, the time must first be converted to local mean solar time based on longitude difference, then adjusted by the equation of time (the difference between true solar time and mean solar time caused by Earth's elliptical orbit and the obliquity of the ecliptic, fluctuating about ±16 minutes over the year). Ignoring this correction may cause a chart to be completely misaligned when the birth hour crosses a boundary. In addition, handling lunar leap months requires care: whether a person born in a leap month should have their life palace placed according to that month or the next month is ambiguously stated in different classical texts. These calendrical details require the charting engine to include astronomical algorithms or call a reliable calendar library rather than simply looking up tables.

From Charting Engine to Knowledge Base: Insights from the Project Architecture

The project doesn't just "calculate" a chart; it also embeds a pattern knowledge base and original classical text data. This design approach deserves attention:

Charting results are structured JSON data, while the knowledge base provides an interpretive layer—which classical passage corresponds to a given pattern, and what the classical interpretation is when a Four Transformation falls in different palaces. This dual-layer architecture of "calculation + knowledge" effectively provides reusable infrastructure for divination-type applications:

1. Engine layer: Pure algorithm—input birth data, output chart—callable by any frontend or API
2. Knowledge layer: Structured classical excerpts and pattern descriptions supporting retrieval and association
3. Extension layer: Developers can build charting apps, AI interpretation assistants, or teaching tools on top of it

A considerable portion of the 6,552 stars likely come from developers interested in fate calculation rather than the purely technical community. This also explains why a vertical-domain project can attract such attention—it fills the tooling gap between "traditional divination" and "modern software engineering".

The pattern knowledge base's structuring approach merits elaboration. "Patterns" in Zi Wei Dou Shu are pattern recognition of specific star combinations—for example, the "Zi Fu Tong Gong" pattern requires Zi Wei and Tian Fu to co-occupy the Yin or Shen palace, while the "Ri Yue Fan Bei" pattern refers to the Sun and Moon occupying unfavorable palaces separately. Traditional texts describe patterns in verse, with vague and overlapping conditions. The knowledge base must decompose each pattern into programmable判定 conditions: which palaces are involved, which stars, whether Four Transformations are required, and whether there are breaking conditions. At the same time, it associates original classical texts as an interpretive layer, so the output not only gives a boolean value of "matches a certain pattern" but also traces the source. This design of "executable rules and verifiable sources" is a key step in turning divination knowledge from oral transmission into auditable digital assets.

The Community Logic of Open-Source Divination Projects

What's worth analyzing is the growth model of such projects. Zi Wei Dou Shu has a broad user base in Chinese cultural circles, but for a long time digital products have been mainly closed-source commercial apps with opaque charting algorithms, leaving users unable to verify results. The emergence of open-source charting engines has changed this situation:

• Auditability: Anyone can check whether the charting logic conforms to the original intent of classical texts
• Reproducibility: Given the same birth data, anyone running the code should get the same chart
• Extensibility: Researchers can modify Four Transformation rules, add new patterns, and conduct comparative experiments

This shares the same underlying driver as the open-source movement in AI—transparency brings trust, and trust brings community participation. The 1,345 forks indicate that many developers are not just using it but attempting customization and secondary development.

Of course, such projects also face unique challenges: the "correctness" of divination rules is itself subject to school disputes, and code implementation must necessarily make trade-offs. The project's choice of the Ni Haixia system as its baseline both clarifies boundaries and may limit adoption by users of other schools.

Practical Value for Developers

If you're a developer, this project offers at least three actionable entry points:

Learn how to model complex rule systems. The charting logic of Zi Wei Dou Shu involves numerous conditional branches and state dependencies, making it good material for practicing domain-driven design. Its TypeScript type definitions can be referenced directly.

Use it as a data foundation for AI applications. Large language models are prone to "hallucinations" when interpreting charts, whereas a structured charting engine can provide precise input data. Feeding engine output to an LLM for interpretation is more reliable than having the model "calculate" directly.

Build cultural tool products. The classical texts and pattern descriptions in the knowledge base are ready-made content assets, suitable for educational or cultural dissemination applications.

The project's single-day growth of 547 stars may involve an element of chance, but the demand it reflects is real: the modern expression of traditional knowledge requires engineered infrastructure. The Zi Wei Dou Shu charting engine is just one sample; similar approaches can be transferred to fields such as traditional Chinese medicine formulas, feng shui compasses, and calendrical calculation. The open-source community is reorganizing these ancient knowledge systems with code.