ziwei-doushu: an open-source Zi Wei Dou Shu chart engine
ziwei-doushu is an open-source TypeScript engine for Zi Wei Dou Shu chart casting, with Four Transformations logic, a pattern library, and MIT licensing.
TL;DR: ziwei-doushu casts Zi Wei Dou Shu charts, the twelve-palace form of Chinese astrology, and it keeps the chart algorithm, the Four Transformations logic and the classical source data together in one MIT licensed TypeScript repository. It sits at 6,892 stars and picked up 546 of them today.
What it is
The repository description is written in Chinese, which tells you who the audience is. The opening phrase, 紫微斗数开源排盘引擎, means an open-source chart-casting engine for Zi Wei Dou Shu. The rest of the line covers the scope: the chart algorithm, the Four Transformations system, a pattern knowledge base, and source data drawn from classical texts. The system it follows is credited to the Tianji material of Ni Haixia.
The code is TypeScript, Next.js shows up among the repository topics, and the package name in package.json is ziwei-master at version 0.1.0. The numbers describe a young project with real traction: 6,892 stars, 1,413 forks, 6 open issues. It was created on 2026-05-01 and last pushed on 2026-10-20.
What the repository contains
| Path | What it holds |
|---|---|
app/ | Next.js application routes |
components/ | React components |
lib/ | Chart logic and shared helpers |
docs/ | Project documentation |
scripts/ | Repository scripts |
tailwind.config.ts | Tailwind CSS setup |
next.config.js | Next.js configuration |
tsconfig.json | TypeScript configuration |
DATASET-LICENSE | Terms covering the bundled classical text data |
LICENSE | MIT license for the code |
README.md, README.en.md | Chinese and English overviews |
Two license files sit side by side at the root, which is the one detail worth flagging before you read anything else.
The stack behind the chart
| Dependency | What it is |
|---|---|
iztro | Zi Wei Dou Shu calculation library |
lunar-javascript | Lunar and solar calendar conversion |
next, react | Application framework and UI runtime |
@anthropic-ai/sdk | Anthropic API client |
pg, ioredis | Postgres and Redis clients |
framer-motion, html2canvas | Animation and image export |
The Vercel analytics packages in the dependency list point to a deployment target, and the bazi topic tag is a pointer to the neighbouring BaZi tradition for anyone arriving from that side.
How to try it
This is a standard Node project, so the path in is the usual one. The package scripts are dev, build, start, typecheck and test.
git clone https://github.com/Renhuai123/ziwei-doushu.git
cd ziwei-doushu
npm install
npm run dev
There is a .env.example at the root and the dependency list includes both a Postgres client and a Redis client, so expect to fill in configuration before the app talks to storage.
npm run typecheck
npm run test
Both scripts exist in package.json, which makes them the two quick checks to run before you change anything.
The data has its own license
Alongside the MIT LICENSE for the code, the repository ships a separate DATASET-LICENSE file for the classical text data held in the knowledge base. Two licenses in one repository means the permission for the code and the permission for the data are not the same thing. If you plan to reuse the bundled texts anywhere else, read that file rather than assuming the MIT terms reach it.
When it fits, and when it does not
Reach for this repository if you want to compute or study Zi Wei Dou Shu charts and would rather read TypeScript than reimplement the astrological rules from scratch. It also works as a reference for how the Four Transformations and the pattern knowledge base are wired on top of a chart.
Two reasons to look elsewhere. The package version is 0.1.0 and the repository dates from May 2026, so treat its interfaces as young and moving. And it does not present itself as a general astrology toolkit, so if BaZi is the requirement rather than a neighbour of it, this is not the project.
Source and Accuracy Notes
- Project page: https://github.com/Renhuai123/ziwei-doushu
- Source repository: Renhuai123/ziwei-doushu (verified via GitHub API
html_url) - License: MIT (verified via GitHub API
license.spdx_id; the repository also ships a separateDATASET-LICENSEfor the bundled classical text data) - Stars at time of writing: 6892
Related Posts
dev-tools
Automotive Skills Suite for AI Engineering
Evaluate Automotive Skills Suite for APQP, ASPICE, HARA, safety-plan, and DIA workflows with setup notes, governance risks, and SME review guidance.
5/28/2026
dev-tools
awesome-agentic-ai-zh Roadmap Guide
Explore awesome-agentic-ai-zh as a Chinese agentic AI learning roadmap, with setup notes, track selection, study workflow, and evaluation guidance.
5/28/2026
dev-tools
Baguette iOS Simulator Automation Guide
Set up Baguette for iOS Simulator automation, web dashboards, device farms, gesture input, streaming, and camera testing with Xcode caveats.
5/28/2026