# skjpt/bazi architecture

> Architecture diagram of the GitHub repository skjpt/bazi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/skjpt/bazi
- Repository: https://github.com/skjpt/bazi

## Overview

1. **Repository purpose**
   - This is an offline, command-line Python toolkit for Chinese metaphysics calculations: 八字排盘 (bazi), 罗喉日时 (luohou), and 生肖合婚 (shengxiao).
   - The repo is not a web service or library package with a central API; it is a set of standalone CLI utilities sharing a common calculation and rule-data layer.

2. **Main entrypoints**
   - `bazi.py` is the primary entrypoint and the most complex application.
   - `luohou.py` computes “罗喉日时” for date-based warnings.
   - `shengxiao.py` maps a user’s zodiac sign to compatibility/conflict relationships.
   - These scripts are separate top-level executables, each focused on a different user-facing calculation.

3. **Shared calculation core**
   - `ganzhi.py` appears to provide the Heavenly Stems / Earthly Branches logic and sexagenary-cycle utilities.
   - `sizi.py` likely models the “four pillars” structure and related derived values used by `bazi.py`.
   - `shen.py` likely contains the “神煞” logic and lookup rules used to annotate charts with auspicious/inauspicious indicators.
   - `shengxiao.py` and `luohou.py` also depend on the same stem/branch foundation rather than reimplementing calendrical rules.

4. **Shared helpers and rule tables**
   - `common.py` is the shared utility layer for formatting, grouping, and reusable computations.
   - `datas.py` likely holds the static datasets: mappings, lookup tables, compatibility relations, and precomputed metaphysical rules.
   - These modules are the main “knowledge base” of the application: the outputs are driven more by tables/rules than by complex business logic.

5. **Calendar and lunar conversion dependency**
   - The repo depends on `sxtwl` for calendar conversion and lunar/solar date calculations, which is critical to all tools that need accurate date-to-pillar mapping.
   - `bidict` is also required, likely to support reversible symbol/name mappings.
   - This external calendar library is a key architectural boundary: the repo’s metaphysics logic sits on top of an imported date-calculation engine.

6. **`bazi.py` subsystem**
   - `bazi.py` orchestrates input parsing, calendar conversion, pillar generation, relationship analysis, five-element scoring, and textual interpretation.
   - Its output combines several layers: raw four pillars, stem/branch interactions, 五行分数, 格局判断, 神煞, and quoted textual judgments.
   - It is the composition layer that pulls together almost all shared modules into one report.

7. **`luohou.py` subsystem**
   - `luohou.py` is a specialized date/time calculator that prints day-by-day warnings about “杀师时”.
   - It likely uses calendar conversion plus a rule table for mapping dates/times to prohibited periods.
   - Compared with `bazi.py`, it is narrower and mostly a formatter over a lookup-driven computation.

8. **`shengxiao.py` subsystem**
   - `shengxiao.py` accepts a zodiac animal as input and returns compatibility, clash, punishment, harm, and break relationships.
   - The data flow is simple: zodiac input → branch mapping → static compatibility tables → human-readable output.
   - It is essentially a deterministic lookup tool with light normalization and formatting.

9. **Reference books and textual interpretations**
   - `books/` contains markdown versions of classical metaphysics texts.
   - The README examples show long judgment passages and historical formula text being emitted in `bazi.py`, so these books likely serve as source material or embedded references for interpretation output.
   - This repo therefore has a “knowledge corpus” boundary separate from the executable code.

10. **Examples and documentation**
   - `examples/` contains markdown examples demonstrating specific chart types or interpretation cases.
   - `README.md` is both user guide and product description, including sample terminal output and dependency notes.
   - These files are not runtime dependencies, but they are important for understanding expected output shape and manual verification.

11. **Conversion / preprocessing path**
   - `convert.py` is likely a utility for transforming source text or structured rules into the markdown/data format used by the repo.
   - Architecturally, this suggests a build/preparation step for maintaining the reference corpus and lookup data, even if the main tools run directly from source.
   - The runtime tools and the content-preparation script are separated.

12. **Overall boundary map**
   - Input boundary: CLI arguments in the three top-level scripts.
   - Core boundary: shared calendrical/stem-branch logic plus lookup tables in `common.py`, `datas.py`, `ganzhi.py`, `shen.py`, and `sizi.py`.
   - External boundary: `sxtwl` for lunar/solar calendar conversion.
   - Output boundary: formatted terminal reports and markdown reference material.

13. **Diagram takeaway**
   - If you draw the architecture, show one central shared domain layer feeding three independent CLI tools.
   - Under the shared layer, emphasize static rule/data modules and the imported calendar library.
   - Around that, show documentation/reference books as supporting content, not as runtime services.

Main entry points: [`bazi.py`](https://github.com/skjpt/bazi/blob/master/bazi.py) (bazi.py), [`luohou.py`](https://github.com/skjpt/bazi/blob/master/luohou.py) (luohou.py), [`shengxiao.py`](https://github.com/skjpt/bazi/blob/master/shengxiao.py) (shengxiao.py), [`ganzhi.py`](https://github.com/skjpt/bazi/blob/master/ganzhi.py) (ganzhi.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI tools"]
  node_bazi_py["bazi.py<br/>bazi calculator<br/>[bazi.py]"]
  node_luohou_py["luohou.py<br/>date warning tool<br/>[luohou.py]"]
  node_shengxiao_py["shengxiao.py<br/>zodiac matcher<br/>[shengxiao.py]"]
end

subgraph group_core["Shared core"]
  node_common_py["common.py<br/>shared helpers<br/>[common.py]"]
  node_datas_py["datas.py<br/>rule tables<br/>[datas.py]"]
  node_ganzhi_py["ganzhi.py<br/>stem-branch core<br/>[ganzhi.py]"]
  node_sizi_py["sizi.py<br/>four pillars<br/>[sizi.py]"]
  node_shen_py["shen.py<br/>shen sha rules<br/>[shen.py]"]
end

subgraph group_content["Reference content"]
  node_convert_py["convert.py<br/>content prep<br/>[convert.py]"]
  node_books["books<br/>classical texts"]
  node_examples["examples<br/>sample outputs"]
  node_readme["README.md<br/>documentation<br/>[README.md]"]
end

subgraph group_external["External deps"]
  node_sxtwl(("sxtwl<br/>calendar library"))
  node_bidict(("bidict<br/>mapping library"))
end

node_bazi_py -->|"formats with"| node_common_py
node_bazi_py -->|"looks up rules"| node_datas_py
node_bazi_py -->|"builds pillars"| node_ganzhi_py
node_bazi_py -->|"models chart"| node_sizi_py
node_bazi_py -->|"annotates chart"| node_shen_py
node_bazi_py -->|"converts date"| node_sxtwl
node_luohou_py -->|"formats with"| node_common_py
node_luohou_py -->|"looks up rules"| node_datas_py
node_luohou_py -->|"maps cycles"| node_ganzhi_py
node_luohou_py -->|"converts date"| node_sxtwl
node_shengxiao_py -->|"formats with"| node_common_py
node_shengxiao_py -->|"looks up relations"| node_datas_py
node_shengxiao_py -->|"normalizes zodiac"| node_ganzhi_py
node_ganzhi_py -->|"uses mapping"| node_bidict
node_convert_py -->|"prepares data"| node_datas_py
node_convert_py -->|"derives from"| node_books
node_convert_py -.->|"validates against"| node_examples
node_readme -.->|"documents"| node_bazi_py
node_readme -.->|"documents"| node_luohou_py
node_readme -.->|"documents"| node_shengxiao_py
node_books -.->|"source material"| node_shen_py
node_examples -.->|"shows output"| node_bazi_py

click node_bazi_py "https://github.com/skjpt/bazi/blob/master/bazi.py"
click node_luohou_py "https://github.com/skjpt/bazi/blob/master/luohou.py"
click node_shengxiao_py "https://github.com/skjpt/bazi/blob/master/shengxiao.py"
click node_common_py "https://github.com/skjpt/bazi/blob/master/common.py"
click node_datas_py "https://github.com/skjpt/bazi/blob/master/datas.py"
click node_ganzhi_py "https://github.com/skjpt/bazi/blob/master/ganzhi.py"
click node_sizi_py "https://github.com/skjpt/bazi/blob/master/sizi.py"
click node_shen_py "https://github.com/skjpt/bazi/blob/master/shen.py"
click node_convert_py "https://github.com/skjpt/bazi/blob/master/convert.py"
click node_books "https://github.com/skjpt/bazi/tree/master/books"
click node_examples "https://github.com/skjpt/bazi/tree/master/examples"
click node_readme "https://github.com/skjpt/bazi/blob/master/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bazi_py,node_luohou_py,node_shengxiao_py toneBlue
class node_common_py,node_datas_py,node_ganzhi_py,node_sizi_py,node_shen_py toneAmber
class node_convert_py,node_books,node_examples,node_readme toneMint
class node_sxtwl,node_bidict toneRose
```

## Components

### CLI tools

Standalone command-line entrypoints for the three user-facing calculators.

- [bazi.py](https://github.com/skjpt/bazi/blob/master/bazi.py): bazi calculator · Main 八字排盘 command; orchestrates chart generation, scoring, rules, and interpretations. · `bazi.py`
- [luohou.py](https://github.com/skjpt/bazi/blob/master/luohou.py): date warning tool · Computes 罗喉日时 warnings from dates and times. · `luohou.py`
- [shengxiao.py](https://github.com/skjpt/bazi/blob/master/shengxiao.py): zodiac matcher · Maps生肖 inputs to compatibility, clash, punishment, harm, and break relationships. · `shengxiao.py`

### Shared core

Calendrical, stem-branch, and rule-data modules reused across tools.

- [common.py](https://github.com/skjpt/bazi/blob/master/common.py): shared helpers · Formatting and reusable utilities shared by the calculators. · `common.py`
- [datas.py](https://github.com/skjpt/bazi/blob/master/datas.py): rule tables · Static mappings, lookup tables, and metaphysics datasets. · `datas.py`
- [ganzhi.py](https://github.com/skjpt/bazi/blob/master/ganzhi.py): stem-branch core · Heavenly stems, earthly branches, and sexagenary-cycle utilities. · `ganzhi.py`
- [sizi.py](https://github.com/skjpt/bazi/blob/master/sizi.py): four pillars · Four-pillars model and derived values used by bazi calculations. · `sizi.py`
- [shen.py](https://github.com/skjpt/bazi/blob/master/shen.py): shen sha rules · Auspicious/inauspicious indicator logic used to annotate charts. · `shen.py`

### Reference content

Classical texts, examples, and documentation supporting interpretation and maintenance.

- [convert.py](https://github.com/skjpt/bazi/blob/master/convert.py): content prep · Preprocessing utility for transforming source material or rules into repo formats. · `convert.py`
- [books](https://github.com/skjpt/bazi/tree/master/books): classical texts · Markdown source texts used as reference material for interpretations. · `books`
- [examples](https://github.com/skjpt/bazi/tree/master/examples): sample outputs · Markdown examples showing chart and interpretation cases. · `examples`
- [README.md](https://github.com/skjpt/bazi/blob/master/README.md): documentation · User guide, examples, and dependency notes for the toolkit. · `README.md`

### External deps

Imported libraries that provide calendar conversion and reversible mappings.

- **sxtwl**: calendar library · External lunar/solar calendar and date-conversion engine.
- **bidict**: mapping library · External reversible mapping helper used for symbol/name conversions.

## Connections

- bazi.py → common.py: formats with · Shares output formatting and reusable helpers.
- bazi.py → datas.py: looks up rules · Consumes static rule tables and domain data.
- bazi.py → ganzhi.py: builds pillars · Uses stem-branch and cycle utilities.
- bazi.py → sizi.py: models chart · Constructs the four-pillars structure.
- bazi.py → shen.py: annotates chart · Adds神煞 and related indicators.
- bazi.py → sxtwl: converts date · Depends on calendar conversion for accurate pillar mapping.
- luohou.py → common.py: formats with · Uses shared helpers for presentation.
- luohou.py → datas.py: looks up rules · Uses date/time prohibition tables.
- luohou.py → ganzhi.py: maps cycles · Relies on stem-branch/date-cycle logic.
- luohou.py → sxtwl: converts date · Uses calendar conversion to derive day/time context.
- shengxiao.py → common.py: formats with · Uses shared helpers for normalization and output.
- shengxiao.py → datas.py: looks up relations · Reads compatibility and conflict tables.
- shengxiao.py → ganzhi.py: normalizes zodiac · Uses branch-based zodiac foundations.
- ganzhi.py → bidict: uses mapping · External reversible mapping support.
- convert.py → datas.py: prepares data · Transforms source material into repository lookup formats.
- convert.py → books: derives from · May consume classical texts while preparing structured data.
- convert.py → examples: validates against · Uses examples as reference cases for prepared outputs.
- README.md → bazi.py: documents · Describes the primary CLI workflow and sample output.
- README.md → luohou.py: documents · Explains the warning calculator usage.
- README.md → shengxiao.py: documents · Explains the zodiac compatibility tool.
- books → shen.py: source material · Classical texts inform interpretation rules and judgments.
- examples → bazi.py: shows output · Illustrates expected chart and interpretation shapes.
