ziwei-doushu: A Ni Haixia-Lineage Zi Wei Dou Shu Charting Engine in TypeScript
紫微斗数开源排盘引擎 — 基于倪海夏《天纪》体系，含完整排盘算法、四化系统、格局知识库、古籍原文数据
At a glance
- What is it?
- Renhuai123/ziwei-doushu open-sources the charting algorithm, the four transformations system, a 1,100-line pattern knowledge base and a 518,400-chart sample dataset, while keeping the AI interpretation prompts and backend routes closed. Here is what you can actually build with it.
- Who is it for?
- Adopt ziwei-doushu if you want a working Next.js charting front end plus a pattern and classics knowledge base you can read and modify, and if you are prepared to write your own /api/interpret route. Do not adopt it expecting a complete product: the AI prompts, backend routes, user system and deployment configuration are explicitly outside the repository, and the README says the AI interpretation feature requires you to implement those interfaces yourself.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 86 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap ziwei-doushu fills: a charting engine without the paywall
Zi Wei Dou Shu software tends to arrive in one of two shapes. There are closed web calculators where you type a birth date and get a chart you cannot inspect, and there are libraries that produce the twelve palaces but stop at the star placements, leaving the pattern reading to the user. This repository sits between those. It publishes the charting flow, the four transformations system, a pattern knowledge base of more than 1,100 lines, and the original classical texts, under the MIT licence for code.
The intended audience is a developer who already knows what a palace is and wants to build on top of one. The README frames the reasoning directly: algorithms are public traditional knowledge and should not be locked behind a wall, while the value sits in interpretation depth and operations. That is why the repository ships a complete Next.js 14 front end but not the backend. If you want a finished reading product, metisziwei.com is the hosted version. If you want a chart engine and a knowledge base to modify, this is the repository.
How the charting pipeline is organised inside lib/ziwei/
The engine is split by concern rather than by feature. lib/ziwei/algorithm.ts carries the full charting flow: locating the life palace, determining the five element bureau, placing the fourteen major stars, placing the auxiliary stars, and laying out the major and annual limits. constants.ts holds the heavenly stems, earthly branches and star constants those routines consume. sihua.ts implements the four transformations (lu, quan, ke, ji) together with the stem-to-transformation lookup table, which is the part most reimplementations get subtly wrong.
patterns.ts is the piece that distinguishes this from a plain library. The README describes it as a pattern knowledge base of over 1,100 lines covering classical configurations such as Zi Fu Tong Gong, Ri Yue Bing Ming and Qi Sha Chao Dou. heming-knowledge.ts holds the compatibility methodology, the logic for comparing two charts under the Ni Haixia system. types.ts defines the TypeScript shapes, and cities.ts provides Chinese city coordinates used for true solar time correction.
Underneath, the project states it builds on iztro plus lunar-javascript for the charting and calendar conversion. So the repository is not a from-scratch ephemeris. It is a structured layer of lineage-specific rules, pattern detection and classical text on top of an existing astrology library. That matters when you evaluate it: the accuracy of the base calendar conversion is inherited, and what you are really adopting is the rule layer and the interface.
Installing ziwei-doushu and getting a chart running locally
The README gives a four-step quick start. Node and npm are assumed; the package.json declares Next.js, React, TypeScript and Tailwind, with iztro and lunar-javascript as the charting dependencies. Clone the repository, install, copy the environment example, then start the dev server.
git clone https://github.com/Renhuai123/ziwei-doushu.git
cd ziwei-doushu
npm install
cp .env.example .env.local
npm run devThe environment file is small. The example sets AI_PROVIDER to deepseek with a DEEPSEEK_API_KEY placeholder, offers a commented-out OpenAI-compatible alternative using MIMO_API_KEY, MIMO_BASE_URL and MIMO_MODEL, and sets NEXT_PUBLIC_SITE_URL to http://localhost:3000.
AI_PROVIDER=deepseek
DEEPSEEK_API_KEY=your-deepseek-api-key
NEXT_PUBLIC_SITE_URL=http://localhost:3000Here is the constraint the README states plainly: the open version does not include the backend API routes, so AI interpretation needs you to implement endpoints such as /api/interpret yourself. The charting algorithm and the front end run independently. What you should see after npm run dev is the charting workbench with the palace grid, palace details and star panel, plus the compatibility page, the classics reader with full-text search, and the encyclopaedia pages for the fourteen major stars and twelve palaces. The AI reading will not appear, because nothing is serving it.
There is also a Cloudflare path in package.json, using @cloudflare/next-on-pages and wrangler, but the README does not document deployment, and the deployment configuration is listed as not open-sourced. Treat build:cf and preview:cf as scripts you would have to validate yourself.
The 518,400-chart dataset and what its licence actually requires
The v3.0-samples release is the part you cannot get from a library. It contains 518,400 samples, described as the full product of 60 years, 12 months, 30 days, 12 hours and 2 sexes, at 5.5 GB split across three compressed volumes. Each sample pairs a chart JSON with interpretation text across thirteen topics, including overall destiny, wealth, career, relationships and health. The README claims the dataset is aligned with the online platform and lists verification figures for male and female differentiation, health content including zi wu liu zhu, and gynaecological content in female charts.
Downloading is a manual step: the three parts and a SHA256SUMS.txt file live on the Releases page, and the README gives merge commands for macOS and Linux using cat, and for Windows PowerShell using Get-Content and Expand-Archive. Verify against the checksum file before using the data; three split archives over 5 GB are exactly where a truncated download hides.
The licence split is the detail worth reading twice. Code under lib/, app/ and components/ is MIT. The classical texts are public domain. The dataset is not MIT: it is free to use commercially, including for model fine-tuning and redistribution, with no fee and no application, but it requires attribution. The README asks for a specific credit line naming the dataset, the repository URL and the author, placed in an About page, a model card, a dataset card, a paper's acknowledgements or a derivative dataset's metadata. That is a real obligation, not a formality, and it is the one condition separating the data from public domain.
Where the open-source boundary bites
The README lists what is not included, and the list is longer than the included list in practical terms. The AI interpretation prompts tuned on the Ni Haixia system are closed. So are the backend routes /api/interpret, /api/heming and /api/generate, the user system with login, SMS verification, membership and payment, the server-side security layer with signature checks, rate limiting and watermarking, and all deployment configuration for Vercel, Nginx, Docker and databases.
The consequence is specific. The repository gives you a chart and a set of pattern rules, but the thing users actually pay for, a written reading, is the part you must build. The README suggests reading patterns.ts and heming-knowledge.ts and combining them with any LLM to construct your own prompt. That is honest, and it also means the quality of your output depends on how well you translate rule structures into prompt context, not on anything shipped here.
Two smaller gaps matter too. The README does not document rollback or versioning for the dataset, so if v4 changes the schema you have no stated migration path. And the repository's own package.json names the project ziwei-master at version 0.1.0, while the release is tagged v3.0-samples, so the version numbers you see in the two places do not describe the same thing. Neither is a defect, but both are things to confirm before you pin a dependency.
ziwei-doushu compared with iztro and with a hosted calculator
The most direct comparison is iztro, the library this project builds on. iztro gives you chart construction and calendar handling as a general-purpose package. ziwei-doushu adds a specific lineage: the Ni Haixia Tian Ji system, an explicit four transformations table, a pattern knowledge base with named classical configurations, compatibility logic for two charts, and the original texts of the Gu Sui Fu, the Zi Wei Dou Shu Quan Ji and the Quan Shu. The difference in approach is scope of opinion. iztro tries to be neutral about interpretation; this repository commits to one school and encodes its rules. If you disagree with that school, the pattern file is where you argue with it.
The second comparison is against a hosted calculator such as the project's own metisziwei.com. A hosted calculator gives you a finished reading and no code. This repository gives you the engine, the rules and the texts, and no reading. Choosing between them is really choosing whether your problem is output or control. If you need to embed charting in a product, customise the palace display, or train on paired data, the repository is the only one of the two that helps. If you need a reading today, it is not.
Maintenance, upgrade cost and licence obligations
The last push to the default branch was on 2026-06-24, and the repository is not archived. The most recent release, v3.0-samples, was published on 2026-05-07. The project is therefore moving, but the cadence is not documented, and there is no stated support policy, no changelog beyond the release tags, and no compatibility guarantee between dataset versions and the TypeScript types. Plan for the upgrade cost to fall on you: if a future dataset release changes the JSON shape, the mapping into lib/ziwei/types.ts is your work.
On licensing, three regimes coexist in one repository. Code under lib/, app/ and components/ is MIT, which requires keeping the LICENSE file. The classical texts are public domain. The dataset requires attribution as described in the README. That means a commercial product built on the samples needs a visible credit, and a fine-tuned model needs the source recorded in its model card. This is a description of what the repository states, not legal advice; if attribution placement matters to your compliance review, have someone read the actual licence text and the dataset section together.
Editorial conclusion
Adopt ziwei-doushu if you want a working Next.js charting front end plus a pattern and classics knowledge base you can read and modify, and if you are prepared to write your own /api/interpret route. Do not adopt it expecting a complete product: the AI prompts, backend routes, user system and deployment configuration are explicitly outside the repository, and the README says the AI interpretation feature requires you to implement those interfaces yourself. Before you commit, verify three things in the code: whether lib/ziwei/algorithm.ts handles true solar time correction on its own or only through lib/ziwei/cities.ts, how many of the 1,100-plus lines in lib/ziwei/patterns.ts are rule definitions versus comments, and whether the sample dataset's JSON schema matches the TypeScript types in lib/ziwei/types.ts.
Frequently asked questions
What is Zi Wei Dou Shu?
It is a Chinese traditional astrology system, and this repository implements a charting engine for it based on the Ni Haixia Tian Ji teaching system. The engine places the fourteen major stars and auxiliary stars into twelve palaces and applies the four transformations.
What is the difference between BaZi and Zi Wei Dou Shu?
The repository does not compare the two systems; it lists bazi only as a topic tag and implements Zi Wei Dou Shu charting. The README describes its own scope as the Ni Haixia Tian Ji lineage with a four transformations system and a pattern knowledge base, and makes no claim about BaZi.
How do you interpret a Zi Wei Dou Shu chart?
The repository ships lib/ziwei/patterns.ts, described as a pattern knowledge base of over 1,100 lines covering configurations such as Zi Fu Tong Gong, Ri Yue Bing Ming and Qi Sha Chao Dou, plus lib/ziwei/heming-knowledge.ts for two-chart comparison. The README states that the AI interpretation prompts are not open-sourced and suggests combining those knowledge files with any LLM to build your own prompt.
Can Zi Wei Dou Shu predict my marriage?
The repository does not make predictive claims. Its scope is charting, pattern rules and the classical texts, and the sample dataset includes interpretation text across thirteen topics. Anything beyond that is the reading layer the project leaves to you.
Is Zi Wei Dou Shu related to Feng Shui?
The repository does not discuss Feng Shui. Its charting pipeline covers palaces, stars, the four transformations and major and annual limits, and the knowledge base covers classical pattern configurations and compatibility between two charts.
Community notes