Ziwei Doushu

6.9K stars
MIT
Active this week
Last commit 3 days ago

Last verified Oct 24, 2026

Build Zi Wei Dou Shu charting apps with a MIT-licensed TypeScript engine, 1,100+ pattern rules, and a 675K-chart interpretation dataset.

Visit website GitHub6.9K

Read the full breakdownWho it is for, how it works, trade-offs, the quick start and the FAQ

who it's for

Who Ziwei Doushu is for#

TypeScript developers building Zi Wei Dou Shu applications

The MIT-licensed engine handles the hard parts: true solar time correction, 1986-1991 daylight saving time, configurable lunar school settings, and 1,100+ pattern rules. Cloning the repo gives you a working Next.js 16 app with a demo chart board, classical text reader, and type-safe interfaces as a foundation. The regression test suite provides a baseline to verify correctness as you extend the engine.

Skip if:

You are building a Bazi (four-pillars) or I Ching application. This engine covers Zi Wei Dou Shu only and does not include Bazi algorithms or hexagram logic.

AI engineers building Chinese astrology RAG or fine-tuning datasets

The 674,976-chart x 13-dimension dataset provides 8.77 million structured interpretation segments, downloadable as JSON Lines files grouped by birth year. The CC BY 4.0 license permits use in commercial AI products with attribution. Each record includes the chart key, birth date, gender, and the full 13-dimension interpretation text in Markdown.

Skip if:

You need real-time, location-corrected interpretations rather than pre-generated static readings, or you need charts for births after 2026 or before 1950. The static dataset uses a fixed 120-degree longitude baseline and covers only that date range.

Researchers studying traditional Chinese metaphysics

The repo includes 1,848 verbatim Ni Haixia lecture quotes from the Tianji series, each with a Bilibili video timestamp for source verification, alongside three complete classical texts (Gusuifu, Quanji, Quanshu) as searchable TypeScript. The SEO knowledge graph in `lib/seo/` provides structured data for 14 main stars across 12 palaces.

Skip if:

You need commercial use rights for the Ni Haixia lecture quotes. That content is licensed CC BY-NC-SA 4.0 and cannot be used in paid products or services.

the problem

The problem it solves#

Developers building Zi Wei Dou Shu tools face a fragmented landscape: commercial platforms lock their chart algorithms behind proprietary APIs, and the few open source implementations are either undocumented, based on informal community approximations, or limited to simple star placements without handling edge cases like true solar time correction, Chinese daylight saving time, or configurable lunar school boundaries.

The deeper problem is that traditional Chinese metaphysical systems require precision: a one-hour error in time calculation changes the palace structure entirely, and different schools of interpretation have different rules for leap months and midnight boundaries. Without an auditable open implementation grounded in canonical texts, developers cannot build trustworthy tools or verify their results against classical sources like the Ziwei Doushu Quanshu.

how Ziwei Doushu solves it

How it solves it#

True Solar Time Correction

Adjusts chart time by the birth location's longitude difference plus the equation of time, preventing misclassification by up to one full shichen (two-hour period) for births at the eastern or western edges of a time zone. A Chinese cities database covers all provinces, including Xinjiang Corps cities and Hainan counties added in the October 2026 update.

1,100+ Classical Pattern Detection Rules

The `patterns.ts` file implements over 1,100 lines of classical pattern rules covering zifu tonggong (Purple and Vault in the same palace), solar and lunar conjunction, qisha chaodou (Seven Killings facing the Dipper), and dozens more. Each rule produces structured TypeScript output that can be consumed by an interpretation layer or used directly in a knowledge graph.

674,976-Chart Interpretation Dataset

The CC BY 4.0 dataset (v4.0) covers births from 1950 to 2026, real calendar dates only, with 13 interpretation dimensions per chart: career, wealth, relationships, health, family, and more. Totaling 8.77 million interpretation segments (56.6 GB uncompressed, 161 MB compressed), it ships in 77 year-based files so you can download only the birth year range you need.

Configurable Lunar School Settings

Four leap-month boundary options (assign to the prior month, the next month, split by day, or treat as its own month) and two midnight day-change strategies let developers match the exact school of interpretation they target. These are explicit configuration switches, not hardcoded assumptions that silently differ from other engines.

Regression-Tested Chart Algorithm

The engine ships with regression tests covering 768 charts: ziwei iron law rules, 1986-1991 Chinese daylight saving time, Spring Festival boundary edge cases, red phoenix and celestial joy star placements, sample time-period consistency, and date legality checks. Tests run automatically in GitHub Actions on every push and pull request.

Classical Text Corpus

Three classical texts are included as structured TypeScript modules: Gusuifu (bone marrow odes), Ziwei Doushu Quanji (Qing dynasty), and Ziwei Doushu Quanshu (Chen Xiyi tradition). The library also includes 1,848 verbatim Ni Haixia lecture quotes from the Tianji series, each with a chapter citation and Bilibili video timestamp.

strengths · trade-offs

Strengths and trade-offs#

Strengths

MIT-Licensed Chart Engine with CC BY 4.0 DatasetThe chart calculation code is MIT licensed, permitting commercial use, modification, and redistribution without licensing fees. The 674,976-chart dataset is CC BY 4.0, which permits commercial use including AI model training. The only requirement for the dataset is attribution naming the source URL and author.
Citation-Verified Pattern RulesEvery interpretation segment in the v4.0 dataset traces to either a verifiable Ni Haixia Tianji lecture quote (cited with chapter and timestamp) or the Ziwei Doushu Quanshu classical text. The October 2026 update removed or replaced any citations that could not be found verbatim in the source, and expanded classical text citations from 244 to 405 entries.
Engine Synchronized with Production WebsiteThe open source engine stays in sync with the production website metisziwei.com on each release. The September 2026 update brought `algorithm.ts` from 181 to 641 lines, added 8 new modules covering true solar time, daylight saving time, lunar-solar conversion, and major cycle context, and cleared 51 GitHub security alerts from 0. Active maintenance is verifiable through the public commit and CI history.
Large Dataset Ready for AI Training or RAGAt 56.6 GB uncompressed, the v4.0 dataset is the largest publicly available Zi Wei Dou Shu interpretation corpus with a permissive license. It is distributed as JSON Lines files, one per year, making it compatible with standard ETL and RAG pipeline tools. Compressed to 161 MB total, the full corpus fits in a single download.

Trade-offs

-Interpretation Library Not IncludedThe `db-analysis.ts` file in the repo is a placeholder stub. The actual 13-theme interpretation text library used by the commercial site is not open source. The pre-generated dataset provides finished output for 1950-2026 births, but if you need to generate new interpretations (different date ranges, updated text, or custom voice), you must build your own interpretation layer using the patterns.ts knowledge base.
-Demo UI Far Behind the Commercial InterfaceThe open source UI is a minimal runnable demo, not a production application. The chart board component is 285 lines in the demo versus 1,334 in the commercial site; the insight panel is 467 lines versus 5,088. If you need a polished, feature-complete UI, plan to build most of it yourself rather than extending the demo.
-No Backend API Routes in Open Source RepoThe AI interpretation endpoint (`/api/interpret`) and the synastry analysis endpoint (`/api/heming`) are not included. Without implementing these yourself, the demo shows charts but cannot deliver narrative readings. The README notes this explicitly: configuring an API key will not make these routes functional in the open source version.
-Dataset Uses Fixed Longitude BaselineAll 674,976 charts in the pre-generated dataset were computed at longitude 120 east without birth-location solar time correction. For research or applications where precise birth-location time matters, the static dataset will diverge from a correctly location-corrected chart. You can regenerate using the engine with location data, but that requires running the full pipeline yourself.

versus alternatives

Ziwei Doushu vs alternatives#

Ziwei Doushu Engine vs Commercial Zi Wei Dou Shu Platforms

Commercial Zi Wei Dou Shu platforms provide polished web applications with AI-powered readings, user accounts, and managed infrastructure. The open source Ziwei Doushu engine is the underlying chart calculation layer: it generates the palace structure, star placements, and pattern judgments, but does not bundle the interpretation text or the production UI.

Feature	Ziwei Doushu (open source)	Commercial platforms
Code license	MIT	Proprietary
Dataset license	CC BY 4.0 (attribution)	Not redistributable
Self-hosting	Yes, browser-side, no backend	No (hosted service)
Chart algorithm	Open, auditable TypeScript	Closed
AI interpretation	Not included	Included
UI completeness	Demo only	Production-ready
Interpretation corpus	674,976 charts, downloadable	Not available

The open source engine is the better choice when you need to audit chart placement logic against classical texts, build a custom interpretation layer, integrate charting into a larger TypeScript application, or train a specialized AI model on Zi Wei Dou Shu data. The CC BY 4.0 dataset is the only large-scale Zi Wei Dou Shu interpretation corpus with a license that permits commercial AI training.

The team's own commercial platform (metisziwei.com, documented in the README) illustrates the gap: its chart board component is 1,334 lines versus 285 in the open source demo; its insight panel is 5,088 lines versus 467. Commercial platforms are the better choice when you need AI-powered narrative readings without building a prompt layer, a polished user interface for non-technical users, or user account and payment management without building those systems yourself.

install · quick start

Quick start#

bash

Self-hosting uses a local Node.js development server with no backend API required.
```bash
git clone https://github.com/Renhuai123/ziwei-doushu.git
cd ziwei-doushu
npm install
npm run dev
```

tech stack · detected from GitHub

What it's built on#

Languages: TypeScript
Frameworks: Next.jsReact
Databases: PostgreSQL
Cache: Redis

frequently asked

FAQ#

Is the interpretation content open source?

Partially. The chart engine code is MIT licensed and fully open. The interpretation text library used on the commercial site is not open source; db-analysis.ts in the repo is a placeholder stub. However, a pre-generated interpretation dataset covering 674,976 charts (1950-2026) across 13 dimensions is available separately under CC BY 4.0, which permits commercial use with attribution. The 1,848 Ni Haixia lecture quotes embedded in interpretations are CC BY-NC-SA 4.0 and cannot be used commercially.

Can I use the dataset to train an AI model?

Yes, for the chart interpretation data. The v4.0 dataset (674,976 charts x 13 dimensions, CC BY 4.0) permits commercial AI training. The only requirement is attribution: cite the dataset name, the source URL (https://github.com/Renhuai123/ziwei-doushu), and the author. The Ni Haixia lecture quotes embedded within interpretations are explicitly excluded from this grant and may not be used commercially.

Does the open source version include AI-powered readings?

No. The /api/interpret and /api/heming endpoints are not in the repo. The demo app renders the chart correctly but displays a notice where AI interpretation would appear. To add narrative readings, you implement your own LLM prompt using lib/ziwei/patterns.ts for the pattern knowledge base and lib/ziwei/heming-knowledge.ts for synastry logic.

How accurate is the chart engine?

The engine includes regression tests covering 768 charts against known good outputs. Tests verify the ziwei iron law rules, 1986-1991 Chinese daylight saving time handling, Spring Festival boundary edge cases, red phoenix and celestial joy placements, sample time-period consistency, and date legality. Five reference charts from classical records were used to verify star placement and brightness defaults in the October 2026 release.

Does the engine handle time zone and location differences?

Yes, for China-based births. The engine includes true solar time correction using longitude and the equation of time, a Chinese cities database covering all provinces (including Xinjiang Corps cities and Hainan counties), and 1986-1991 daylight saving time handling. For births outside China, pass the birth longitude directly; the dataset baseline uses 120 degrees east with no per-location correction applied.

also worth a look

Similar open-source tools#

Lean

Alternative toQuantConnect

Algorithmic trading engine for backtesting and live trading

22,159 GitHub stars
Licence Apache-2.0

Shadowbroker

Alternative toRecorded Future

Self-hosted OSINT map: aircraft, ships, CCTV, satellites, 60+ feeds.

11,344 GitHub stars
Licence AGPL-3.0

Freehire

Alternative toSimplify.jobs

Open source job search with 3.3M+ postings direct from company boards.

2,397 GitHub stars
Licence MIT

Worldmonitor

Alternative toSeerist

Self-hosted geopolitical risk map: 58 layer types, 469 OSINT feeds.

89,354 GitHub stars
Licence AGPL-3.0

Google Maps Scraper

Alternative toOutscraper

Google Maps lead extractor with batch keywords and CSV export

Licence MIT

Deviload

Alternative to4K Video Downloader Plus

yt-dlp desktop app with media library, player, and editor

174 GitHub stars
Licence MIT

by category

12,787 GitHub stars
Licence AGPL-3.0
#Email

rakazo

Alternative toGrok Bot

AI teammates you own: your keys, your model, your machine.

5,406 GitHub stars
Licence Apache-2.0
#AI Agents

Omnara

Alternative toClaude Managed Agents

Open-source agent deployment API. Self-host or use Omnara Cloud.

2,957 GitHub stars
Licence Apache-2.0
#AI Agents

Feature your project

The projects we add and every new guide. Free, unsubscribe any time.

Find open source alternatives to paid software

Ziwei Doushu Engine vs Commercial Zi Wei Dou Shu Platforms

Feature	Ziwei Doushu (open source)	Commercial platforms
Code license	MIT	Proprietary
Dataset license	CC BY 4.0 (attribution)	Not redistributable
Self-hosting	Yes, browser-side, no backend	No (hosted service)
Chart algorithm	Open, auditable TypeScript	Closed
AI interpretation	Not included	Included
UI completeness	Demo only	Production-ready
Interpretation corpus	674,976 charts, downloadable	Not available

Who Ziwei Doushu is for#

TypeScript developers building Zi Wei Dou Shu applications

Skip if:

AI engineers building Chinese astrology RAG or fine-tuning datasets

Skip if:

Researchers studying traditional Chinese metaphysics

Skip if:

The problem it solves#

How it solves it#

True Solar Time Correction

1,100+ Classical Pattern Detection Rules

674,976-Chart Interpretation Dataset

Configurable Lunar School Settings

Regression-Tested Chart Algorithm

Classical Text Corpus

Strengths and trade-offs#

Strengths

Trade-offs

Ziwei Doushu vs alternatives#

Ziwei Doushu Engine vs Commercial Zi Wei Dou Shu Platforms

Quick start#

What it's built on#

FAQ#

Similar open-source tools#

Open source tools in these categories#

Web & App Development

Data & Analytics

Find open source alternatives to paid software

Who Ziwei Doushu is for#

TypeScript developers building Zi Wei Dou Shu applications

Skip if:

AI engineers building Chinese astrology RAG or fine-tuning datasets

Skip if:

Researchers studying traditional Chinese metaphysics

Skip if:

The problem it solves#

How it solves it#

True Solar Time Correction

1,100+ Classical Pattern Detection Rules

674,976-Chart Interpretation Dataset

Configurable Lunar School Settings

Regression-Tested Chart Algorithm

Classical Text Corpus

Strengths and trade-offs#

Strengths

Trade-offs

Ziwei Doushu vs alternatives#

Ziwei Doushu Engine vs Commercial Zi Wei Dou Shu Platforms

Quick start#

What it's built on#

FAQ#

Similar open-source tools#

Open source tools in these categories#

Web & App Development

Data & Analytics

Find open source alternatives to paid software