perfhelf/bigfishmarquis-qimen

Purpose and Entry Points

This is a pure TypeScript Qimen Dun Jia chart-generation library. It produces yearly, monthly, daily, and hourly charts, with interpretation of resulting patterns. The primary unified entry point is src/engine.ts; callers may also invoke method- or layer-specific generators directly, especially src/engines/shijia.ts.

Domain Contract and Static Model

src/types.ts defines the chart/domain contracts shared across generators and interpretation. src/constants.ts centralizes calendrical, palace, stem/branch, and Qimen ordering rules. These form the boundary between caller-supplied calendrical inputs—GanZhi, solar terms, dates/four pillars—and deterministic chart output.

Unified Dispatch and Layer Selection

src/engine.ts routes a requested chart layer and applicable method to the proper engine. The system separates:

• annual charting: src/engines/nianjia.ts

• monthly charting: src/engines/yuejia.ts

• daily charting: src/engines/rijia.ts

• hourly charting: src/engines/shijia.ts

Year/month/day logic shares common placement behavior through src/engines/shared.ts; hourly generation has its own fuller construction path.

Hourly Ju Determination

Hourly charting first determines Yin/Yang Dun, Ju number, and Yuan from a solar term plus GanZhi context. Three alternative strategies are isolated behind:

• ChaiBu: src/engines/chaibuquju.ts

• MaoShan: src/engines/maoshan.ts

• ZhiRun: src/engines/zhirun.ts

Their output feeds src/engines/shijia.ts, which builds the final hourly palace layout and associated elements. This separation lets consumers select calendrical tradition without replacing chart construction.

Chart Construction

The chart engines calculate and arrange core Qimen layers: nine-palace earth/heaven plates, stars, doors, gods, hidden stems, duty relationships, lodging behavior, voids, post-horse, and tomb/punishment/pressure markers. src/engines/shijia.ts is the central high-detail assembly stage, while src/engines/shared.ts supplies reusable layer-placement mechanics for non-hourly charts.

Interpretation Pipeline

src/interpretation.ts consumes generated chart state and identifies classical patterns and correspondences. It combines structural chart relationships with reference content for 81 patterns, ten-stem interactions, duty-star correspondences, deity selection, and strategic guidance. Interpretation is downstream of chart generation, so chart creation can be used independently of textual analysis.

Data, Runtime, and External Boundaries

Reference knowledge is packaged as repository JSON, including palace/star/door/god definitions and interpretation texts: src/data/gong_wei.json, src/data/ge_ju_duan_yu.json, and src/data/shi_gan_ke_ying.json. The runtime has no required external engine or service. Upstream callers must provide or derive solar-term and GanZhi/four-pillar inputs; lunar-javascript or lunar-typescript is optional for that calendrical acquisition boundary.