dev-tools 4 min read

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.

#github-trending #ziwei-doushu #typescript #chinese-astrology #open-source
By
Share: X in
GitHub social preview card for Renhuai123/ziwei-doushu

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

PathWhat it holds
app/Next.js application routes
components/React components
lib/Chart logic and shared helpers
docs/Project documentation
scripts/Repository scripts
tailwind.config.tsTailwind CSS setup
next.config.jsNext.js configuration
tsconfig.jsonTypeScript configuration
DATASET-LICENSETerms covering the bundled classical text data
LICENSEMIT license for the code
README.md, README.en.mdChinese 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

DependencyWhat it is
iztroZi Wei Dou Shu calculation library
lunar-javascriptLunar and solar calendar conversion
next, reactApplication framework and UI runtime
@anthropic-ai/sdkAnthropic API client
pg, ioredisPostgres and Redis clients
framer-motion, html2canvasAnimation 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 separate DATASET-LICENSE for the bundled classical text data)
  • Stars at time of writing: 6892