# perfhelf/bigfishmarquis-qimen architecture

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

- Interactive diagram: https://gitdiagram.com/perfhelf/bigfishmarquis-qimen
- Repository: https://github.com/perfhelf/bigfishmarquis-qimen

## Overview

#### 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.

Main entry points: [`src/engine.ts`](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engine.ts) (Unified engine), [`src/engines/shijia.ts`](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/shijia.ts) (Hourly generator), [`src/interpretation.ts`](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/interpretation.ts) (Pattern interpretation), [`src/engines/shared.ts`](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/shared.ts) (Shared placement)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_caller(("Caller calendrical input<br/>external input"))
  node_optional_calendar["Optional calendar library<br/>optional dependency"]
  node_types["Domain contracts<br/>TypeScript types<br/>[types.ts]"]
  node_constants["Qimen rules<br/>static model<br/>[constants.ts]"]
end

subgraph group_generation["Chart Generation"]
  node_engine{{"Unified engine<br/>dispatcher<br/>[engine.ts]"}}
  node_nianjia["Annual generator<br/>chart engine<br/>[nianjia.ts]"]
  node_yuejia["Monthly generator<br/>chart engine<br/>[yuejia.ts]"]
  node_rijia["Daily generator<br/>chart engine<br/>[rijia.ts]"]
  node_shared["Shared placement<br/>layer mechanics<br/>[shared.ts]"]
  node_shijia{{"Hourly generator<br/>chart assembler<br/>[shijia.ts]"}}
  node_chaibu["ChaiBu Ju strategy<br/>[chaibuquju.ts]"]
  node_maoshan["MaoShan Ju strategy<br/>[maoshan.ts]"]
  node_zhirun["ZhiRun Ju strategy<br/>[zhirun.ts]"]
  node_chart["Generated chart<br/>domain output"]
end

subgraph group_knowledge["Interpretation Knowledge"]
  node_interpretation{{"Pattern interpretation<br/>analysis pipeline<br/>[interpretation.ts]"}}
  node_pattern_data[("Pattern reference texts<br/>JSON knowledge<br/>[ge_ju_duan_yu.json]")]
  node_stem_data[("Stem interaction data<br/>JSON knowledge")]
  node_palace_data[("Palace reference data<br/>JSON knowledge<br/>[gong_wei.json]")]
  node_guidance["Interpretation result<br/>analysis output"]
end

node_optional_calendar -.->|"derives inputs"| node_caller
node_caller -->|"chart request"| node_engine
node_types -->|"contracts"| node_engine
node_constants -->|"rules"| node_engine
node_engine -->|"annual"| node_nianjia
node_engine -->|"monthly"| node_yuejia
node_engine -->|"daily"| node_rijia
node_engine -->|"hourly"| node_shijia
node_nianjia -->|"placement"| node_shared
node_yuejia -->|"placement"| node_shared
node_rijia -->|"placement"| node_shared
node_chaibu -->|"Yin/Yang Dun, Ju, Yuan"| node_shijia
node_maoshan -->|"Yin/Yang Dun, Ju, Yuan"| node_shijia
node_zhirun -->|"Yin/Yang Dun, Ju, Yuan"| node_shijia
node_shared -->|"non-hourly layers"| node_chart
node_shijia -->|"hourly layout"| node_chart
node_chart -->|"chart state"| node_interpretation
node_pattern_data -->|"pattern texts"| node_interpretation
node_stem_data -->|"stem interactions"| node_interpretation
node_palace_data -->|"definitions"| node_interpretation
node_interpretation -->|"findings"| node_guidance

click node_types "https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/types.ts"
click node_constants "https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/constants.ts"
click node_engine "https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engine.ts"
click node_nianjia "https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/nianjia.ts"
click node_yuejia "https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/yuejia.ts"
click node_rijia "https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/rijia.ts"
click node_shared "https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/shared.ts"
click node_shijia "https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/shijia.ts"
click node_chaibu "https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/chaibuquju.ts"
click node_maoshan "https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/maoshan.ts"
click node_zhirun "https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/zhirun.ts"
click node_interpretation "https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/interpretation.ts"
click node_pattern_data "https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/data/ge_ju_duan_yu.json"
click node_stem_data "https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/data/shi_gan_ke_ying.json"
click node_palace_data "https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/data/gong_wei.json"

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_caller,node_optional_calendar,node_types,node_constants toneBlue
class node_engine,node_nianjia,node_yuejia,node_rijia,node_shared,node_shijia,node_chaibu,node_maoshan,node_zhirun,node_chart toneAmber
class node_interpretation,node_pattern_data,node_stem_data,node_palace_data,node_guidance toneMint
```

## Components

### Public API

- **Caller calendrical input**: external input · Solar terms, GanZhi, dates, and four pillars.
- **Optional calendar library**: optional dependency · May derive calendrical inputs before chart generation.
- [Domain contracts](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/types.ts): TypeScript types · Shared chart and input contracts. · `src/types.ts`
- [Qimen rules](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/constants.ts): static model · Calendrical orderings and palace, stem, and branch rules. · `src/constants.ts`

### Chart Generation

- [Unified engine](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engine.ts): dispatcher · Selects chart layer and applicable method. · `src/engine.ts`
- [Annual generator](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/nianjia.ts): chart engine · `src/engines/nianjia.ts`
- [Monthly generator](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/yuejia.ts): chart engine · `src/engines/yuejia.ts`
- [Daily generator](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/rijia.ts): chart engine · `src/engines/rijia.ts`
- [Shared placement](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/shared.ts): layer mechanics · Reusable placement behavior for annual, monthly, and daily charts. · `src/engines/shared.ts`
- [Hourly generator](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/shijia.ts): chart assembler · Builds the detailed hourly palace layout and related markers. · `src/engines/shijia.ts`
- [ChaiBu Ju strategy](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/chaibuquju.ts): Ju strategy · `src/engines/chaibuquju.ts`
- [MaoShan Ju strategy](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/maoshan.ts): Ju strategy · `src/engines/maoshan.ts`
- [ZhiRun Ju strategy](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/engines/zhirun.ts): Ju strategy · `src/engines/zhirun.ts`
- **Generated chart**: domain output · Palace layers, duty relations, voids, post-horse, and markers.

### Interpretation Knowledge

- [Pattern interpretation](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/interpretation.ts): analysis pipeline · Derives classical patterns, correspondences, and guidance from chart state. · `src/interpretation.ts`
- [Pattern reference texts](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/data/ge_ju_duan_yu.json): JSON knowledge · 81-pattern and ten-stem interaction texts. · `src/data/ge_ju_duan_yu.json`
- [Stem interaction data](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/data/shi_gan_ke_ying.json): JSON knowledge · `src/data/shi_gan_ke_ying.json`
- [Palace reference data](https://github.com/perfhelf/bigfishmarquis-qimen/blob/main/src/data/gong_wei.json): JSON knowledge · Palace, star, door, and god definitions. · `src/data/gong_wei.json`
- **Interpretation result**: analysis output · Detected patterns and strategic guidance.

## Connections

- Optional calendar library → Caller calendrical input: derives inputs
- Caller calendrical input → Unified engine: chart request
- Domain contracts → Unified engine: contracts
- Qimen rules → Unified engine: rules
- Unified engine → Annual generator: annual
- Unified engine → Monthly generator: monthly
- Unified engine → Daily generator: daily
- Unified engine → Hourly generator: hourly
- Annual generator → Shared placement: placement
- Monthly generator → Shared placement: placement
- Daily generator → Shared placement: placement
- ChaiBu Ju strategy → Hourly generator: Yin/Yang Dun, Ju, Yuan
- MaoShan Ju strategy → Hourly generator: Yin/Yang Dun, Ju, Yuan
- ZhiRun Ju strategy → Hourly generator: Yin/Yang Dun, Ju, Yuan
- Shared placement → Generated chart: non-hourly layers
- Hourly generator → Generated chart: hourly layout
- Generated chart → Pattern interpretation: chart state
- Pattern reference texts → Pattern interpretation: pattern texts
- Stem interaction data → Pattern interpretation: stem interactions
- Palace reference data → Pattern interpretation: definitions
- Pattern interpretation → Interpretation result: findings