# h4x0r/stem-branch architecture

> Architecture diagram of the GitHub repository h4x0r/stem-branch, 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/h4x0r/stem-branch
- Repository: https://github.com/h4x0r/stem-branch

## Overview

#### Purpose and entry points
`stem-branch` is a zero-dependency TypeScript library for Chinese calendrical, astronomical, astrological, and divination computation, with a Rust solar-ephemeris port. The public library boundary is `src/index.ts`; package/TS build settings are `package.json` and `tsup.config.ts`. A command-line interface begins at `src/cli.ts` and delegates formatted output to renderers under `src/cli/`.

#### Astronomical computation core
Solar, lunar, and time-scale calculations provide the numerical foundation for higher-level systems. Solar longitude and terms are centered on `src/solar-longitude.ts`, `src/solar-terms.ts`, and the VSOP87D Earth series in `src/vsop87d-earth.ts`. Lunar position, phases, and conjunctions are handled through `src/moon/moon.ts`, `src/new-moon.ts`, and `src/lunisolar-calendar.ts`. Julian-date conversion and ΔT establish the UTC/TT time boundary in `src/julian-day.ts` and `src/delta-t.ts`.

#### Ephemerides and planetary layer
The library computes geocentric planetary positions and related observational data rather than calling a runtime ephemeris service. The integration layer is `src/planets/planets.ts`, using geocentric transformations in `src/planets/geocentric.ts` and planet-specific VSOP/other models under `src/planets/`. Eclipse lookup/calculation is separated in `src/eclipses.ts` and `src/eclipse-data.ts`. Generated/reference coefficient data originates from local sources such as `data/VSOP87D.ear` and generation scripts in `data/`.

#### Calendar and Chinese metaphysics layer
Lunisolar dates and solar-term boundaries feed stem-branch and Four Pillars derivation. Core cycle primitives live in `src/stems.ts`, `src/branches.ts`, and `src/stem-branch.ts`; pillar computation is in `src/four-pillars.ts`. The aggregate daily API, `src/daily-almanac.ts`, composes pillars, lunar date, fitness, flags, Six Ren, flying stars, eclipses, and element analysis. Almanac-specific rules remain modular, including `src/almanac-flags.ts`, `src/day-fitness.ts`, and `src/flying-stars.ts`.

#### Chart and divination subsystems
Independent domain modules consume the shared calendar/astronomy layer rather than each other’s presentation code. Six Ren and Qi Men are rooted in `src/six-ren.ts` and `src/qimen-chuanren.ts`. Western/tropical and sidereal computations are in `src/tropical-astrology.ts` and `src/sidereal-astrology.ts`. Seven Governors is a substantial bounded subsystem: `src/seven-governors/chart.ts` orchestrates bodies, ascendant, mansions, palaces, aspects, and dignities from modules under `src/seven-governors/`.

#### User-facing surfaces
The CLI dispatches commands from `src/cli.ts`; specialized renderers, such as `src/cli/render-almanac.ts` and `src/cli/render-seven-governors.ts`, are presentation-only consumers of library APIs. A separate Next.js Almanac UI resides under `almanac/src/app/page.tsx`, with its main client presentation in `almanac/src/components/almanac-view.tsx`; formatting/export are isolated in `almanac/src/lib/format-almanac.ts` and `almanac/src/lib/export-html.ts`. Documentation is a VitePress site configured by `docs/.vitepress/config.ts`.

#### Rust parity and validation boundary
`rust/` is an independent native implementation of the solar ephemeris core, exposed through `rust/src/lib.rs` and implemented primarily in `rust/src/vsop87d_earth.rs`, `rust/src/solar_terms.rs`, and `rust/src/moon.rs`. It has no JavaScript dependency at runtime. TypeScript-generated coefficient tables are represented in Rust data modules such as `rust/src/elpmpp02_data.rs`. JPL DE441, Hong Kong Observatory, Swiss Ephemeris, and other datasets are validation/reference inputs represented by local fixtures and generation scripts; they are not required production services.

Main entry points: [`src/daily-almanac.ts`](https://github.com/h4x0r/stem-branch/blob/main/src/daily-almanac.ts) (Daily Almanac), [`src/lunisolar-calendar.ts`](https://github.com/h4x0r/stem-branch/blob/main/src/lunisolar-calendar.ts) (Lunar phases & calendar), [`src/index.ts`](https://github.com/h4x0r/stem-branch/blob/main/src/index.ts) (Public API), [`src/four-pillars.ts`](https://github.com/h4x0r/stem-branch/blob/main/src/four-pillars.ts) (Four Pillars)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ts["TypeScript library"]
  node_public_api["Public API<br/>TypeScript entry<br/>[index.ts]"]
  node_cli["CLI dispatcher<br/>TypeScript CLI<br/>[cli.ts]"]
end

subgraph group_astro["Astronomy core"]
  node_time_scale["Julian dates &amp; ΔT<br/>time conversion<br/>[julian-day.ts]"]
  node_solar["Solar longitude &amp; terms<br/>solar computation<br/>[solar-longitude.ts]"]
  node_earth_series["VSOP87D Earth series<br/>coefficient model<br/>[vsop87d-earth.ts]"]
  node_lunar["Lunar phases &amp; calendar<br/>lunar computation"]
  node_planets["Planetary positions<br/>ephemeris integration<br/>[planets.ts]"]
  node_eclipses["Eclipse calculation<br/>astronomy domain<br/>[eclipses.ts]"]
end

subgraph group_domains["Calendars and charts"]
  node_cycles["Stem-branch cycles<br/>calendar primitive<br/>[stem-branch.ts]"]
  node_four_pillars["Four Pillars<br/>calendar derivation<br/>[four-pillars.ts]"]
  node_daily_almanac["Daily Almanac<br/>aggregate API<br/>[daily-almanac.ts]"]
  node_six_ren_qimen["Six Ren &amp; Qi Men<br/>divination subsystem<br/>[six-ren.ts]"]
  node_astrology["Tropical &amp; sidereal astrology<br/>astrology subsystem"]
  node_seven_governors["Seven Governors chart<br/>chart subsystem<br/>[chart.ts]"]
end

subgraph group_surfaces["User surfaces"]
  node_cli_renderers["CLI renderers<br/>presentation<br/>[render-almanac.ts]"]
  node_almanac_ui["Next.js Almanac UI<br/>web application<br/>[page.tsx]"]
  node_almanac_view["Almanac client view<br/>client presentation<br/>[almanac-view.tsx]"]
  node_docs["Documentation site<br/>VitePress site<br/>[config.ts]"]
end

subgraph group_rust["Rust parity core"]
  node_rust_api["Rust library API<br/>Rust entry<br/>[lib.rs]"]
  node_rust_solar["Rust solar ephemeris<br/>Rust computation<br/>[vsop87d_earth.rs]"]
  node_rust_terms_moon["Rust terms &amp; moon<br/>Rust computation<br/>[solar_terms.rs]"]
end

node_public_api -->|"exports"| node_daily_almanac
node_public_api -->|"exports"| node_six_ren_qimen
node_public_api -->|"exports"| node_astrology
node_public_api -->|"exports"| node_seven_governors
node_cli -->|"dispatches to"| node_cli_renderers
node_cli_renderers -->|"formats"| node_daily_almanac
node_cli_renderers -->|"formats"| node_seven_governors
node_solar -->|"uses"| node_earth_series
node_solar -->|"uses"| node_time_scale
node_lunar -->|"uses term boundaries"| node_solar
node_lunar -->|"uses"| node_time_scale
node_planets -->|"uses"| node_time_scale
node_eclipses -->|"uses"| node_lunar
node_four_pillars -->|"derives"| node_cycles
node_four_pillars -->|"uses"| node_lunar
node_daily_almanac -->|"composes"| node_four_pillars
node_daily_almanac -->|"composes"| node_lunar
node_daily_almanac -->|"includes"| node_eclipses
node_six_ren_qimen -->|"uses shared calendar"| node_four_pillars
node_astrology -->|"uses positions"| node_planets
node_seven_governors -->|"uses bodies"| node_planets
node_almanac_ui -->|"hosts"| node_almanac_view
node_almanac_view -->|"consumes"| node_daily_almanac
node_rust_api -->|"exposes"| node_rust_solar
node_rust_api -->|"exposes"| node_rust_terms_moon
node_rust_terms_moon -->|"uses"| node_rust_solar
node_rust_solar -.->|"parity with"| node_earth_series

click node_public_api "https://github.com/h4x0r/stem-branch/blob/main/src/index.ts"
click node_cli "https://github.com/h4x0r/stem-branch/blob/main/src/cli.ts"
click node_time_scale "https://github.com/h4x0r/stem-branch/blob/main/src/julian-day.ts"
click node_solar "https://github.com/h4x0r/stem-branch/blob/main/src/solar-longitude.ts"
click node_earth_series "https://github.com/h4x0r/stem-branch/blob/main/src/vsop87d-earth.ts"
click node_lunar "https://github.com/h4x0r/stem-branch/blob/main/src/lunisolar-calendar.ts"
click node_planets "https://github.com/h4x0r/stem-branch/blob/main/src/planets/planets.ts"
click node_eclipses "https://github.com/h4x0r/stem-branch/blob/main/src/eclipses.ts"
click node_cycles "https://github.com/h4x0r/stem-branch/blob/main/src/stem-branch.ts"
click node_four_pillars "https://github.com/h4x0r/stem-branch/blob/main/src/four-pillars.ts"
click node_daily_almanac "https://github.com/h4x0r/stem-branch/blob/main/src/daily-almanac.ts"
click node_six_ren_qimen "https://github.com/h4x0r/stem-branch/blob/main/src/six-ren.ts"
click node_astrology "https://github.com/h4x0r/stem-branch/blob/main/src/tropical-astrology.ts"
click node_seven_governors "https://github.com/h4x0r/stem-branch/blob/main/src/seven-governors/chart.ts"
click node_cli_renderers "https://github.com/h4x0r/stem-branch/blob/main/src/cli/render-almanac.ts"
click node_almanac_ui "https://github.com/h4x0r/stem-branch/blob/main/almanac/src/app/page.tsx"
click node_almanac_view "https://github.com/h4x0r/stem-branch/blob/main/almanac/src/components/almanac-view.tsx"
click node_docs "https://github.com/h4x0r/stem-branch/blob/main/docs/.vitepress/config.ts"
click node_rust_api "https://github.com/h4x0r/stem-branch/blob/main/rust/src/lib.rs"
click node_rust_solar "https://github.com/h4x0r/stem-branch/blob/main/rust/src/vsop87d_earth.rs"
click node_rust_terms_moon "https://github.com/h4x0r/stem-branch/blob/main/rust/src/solar_terms.rs"

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_public_api,node_cli toneBlue
class node_time_scale,node_solar,node_earth_series,node_lunar,node_planets,node_eclipses toneAmber
class node_cycles,node_four_pillars,node_daily_almanac,node_six_ren_qimen,node_astrology,node_seven_governors toneMint
class node_cli_renderers,node_almanac_ui,node_almanac_view,node_docs toneRose
class node_rust_api,node_rust_solar,node_rust_terms_moon toneIndigo
```

## Components

### TypeScript library

Public computation library and CLI.

- [Public API](https://github.com/h4x0r/stem-branch/blob/main/src/index.ts): TypeScript entry · `src/index.ts`
- [CLI dispatcher](https://github.com/h4x0r/stem-branch/blob/main/src/cli.ts): TypeScript CLI · `src/cli.ts`

### Astronomy core

Numerical time, solar, lunar, and planetary foundations.

- [Julian dates & ΔT](https://github.com/h4x0r/stem-branch/blob/main/src/julian-day.ts): time conversion · Establishes UTC and TT calculation boundaries. · `src/julian-day.ts`
- [Solar longitude & terms](https://github.com/h4x0r/stem-branch/blob/main/src/solar-longitude.ts): solar computation · `src/solar-longitude.ts`
- [VSOP87D Earth series](https://github.com/h4x0r/stem-branch/blob/main/src/vsop87d-earth.ts): coefficient model · `src/vsop87d-earth.ts`
- [Lunar phases & calendar](https://github.com/h4x0r/stem-branch/blob/main/src/lunisolar-calendar.ts): lunar computation · `src/lunisolar-calendar.ts`
- [Planetary positions](https://github.com/h4x0r/stem-branch/blob/main/src/planets/planets.ts): ephemeris integration · Computes geocentric positions from local models. · `src/planets/planets.ts`
- [Eclipse calculation](https://github.com/h4x0r/stem-branch/blob/main/src/eclipses.ts): astronomy domain · `src/eclipses.ts`

### Calendars and charts

Higher-level calendrical and astrological systems.

- [Stem-branch cycles](https://github.com/h4x0r/stem-branch/blob/main/src/stem-branch.ts): calendar primitive · `src/stem-branch.ts`
- [Four Pillars](https://github.com/h4x0r/stem-branch/blob/main/src/four-pillars.ts): calendar derivation · `src/four-pillars.ts`
- [Daily Almanac](https://github.com/h4x0r/stem-branch/blob/main/src/daily-almanac.ts): aggregate API · Composes calendar, rules, charts, eclipses, and element analysis. · `src/daily-almanac.ts`
- [Six Ren & Qi Men](https://github.com/h4x0r/stem-branch/blob/main/src/six-ren.ts): divination subsystem · `src/six-ren.ts`
- [Tropical & sidereal astrology](https://github.com/h4x0r/stem-branch/blob/main/src/tropical-astrology.ts): astrology subsystem · `src/tropical-astrology.ts`
- [Seven Governors chart](https://github.com/h4x0r/stem-branch/blob/main/src/seven-governors/chart.ts): chart subsystem · Orchestrates bodies, ascendant, mansions, palaces, aspects, and dignities. · `src/seven-governors/chart.ts`

### User surfaces

CLI, web UI, and documentation.

- [CLI renderers](https://github.com/h4x0r/stem-branch/blob/main/src/cli/render-almanac.ts): presentation · `src/cli/render-almanac.ts`
- [Next.js Almanac UI](https://github.com/h4x0r/stem-branch/blob/main/almanac/src/app/page.tsx): web application · `almanac/src/app/page.tsx`
- [Almanac client view](https://github.com/h4x0r/stem-branch/blob/main/almanac/src/components/almanac-view.tsx): client presentation · `almanac/src/components/almanac-view.tsx`
- [Documentation site](https://github.com/h4x0r/stem-branch/blob/main/docs/.vitepress/config.ts): VitePress site · `docs/.vitepress/config.ts`

### Rust parity core

Independent native solar-ephemeris implementation.

- [Rust library API](https://github.com/h4x0r/stem-branch/blob/main/rust/src/lib.rs): Rust entry · Independent from JavaScript at runtime. · `rust/src/lib.rs`
- [Rust solar ephemeris](https://github.com/h4x0r/stem-branch/blob/main/rust/src/vsop87d_earth.rs): Rust computation · `rust/src/vsop87d_earth.rs`
- [Rust terms & moon](https://github.com/h4x0r/stem-branch/blob/main/rust/src/solar_terms.rs): Rust computation · `rust/src/solar_terms.rs`

## Connections

- Public API → Daily Almanac: exports
- Public API → Six Ren & Qi Men: exports
- Public API → Tropical & sidereal astrology: exports
- Public API → Seven Governors chart: exports
- CLI dispatcher → CLI renderers: dispatches to
- CLI renderers → Daily Almanac: formats
- CLI renderers → Seven Governors chart: formats
- Solar longitude & terms → VSOP87D Earth series: uses
- Solar longitude & terms → Julian dates & ΔT: uses
- Lunar phases & calendar → Solar longitude & terms: uses term boundaries
- Lunar phases & calendar → Julian dates & ΔT: uses
- Planetary positions → Julian dates & ΔT: uses
- Eclipse calculation → Lunar phases & calendar: uses
- Four Pillars → Stem-branch cycles: derives
- Four Pillars → Lunar phases & calendar: uses
- Daily Almanac → Four Pillars: composes
- Daily Almanac → Lunar phases & calendar: composes
- Daily Almanac → Eclipse calculation: includes
- Six Ren & Qi Men → Four Pillars: uses shared calendar
- Tropical & sidereal astrology → Planetary positions: uses positions
- Seven Governors chart → Planetary positions: uses bodies
- Next.js Almanac UI → Almanac client view: hosts
- Almanac client view → Daily Almanac: consumes
- Rust library API → Rust solar ephemeris: exposes
- Rust library API → Rust terms & moon: exposes
- Rust terms & moon → Rust solar ephemeris: uses
- Rust solar ephemeris → VSOP87D Earth series: parity with