# tommitoan/bazica architecture

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

- Interactive diagram: https://gitdiagram.com/tommitoan/bazica
- Repository: https://github.com/tommitoan/bazica

## Overview

##### Project type and purpose
- This is a Go library (`bazica`) for computing Chinese astrology Ba-Zi (Four Pillars) charts, not a standalone service or full-stack app.
- Its public entry point is the `GetBaziChart` function, which, given a `time.Time`, location and gender, returns a structured Ba-Zi chart.

##### File structure
Top level
- get_bazi_chart.go        — public API entry point
- data/                    — JSON fixtures (solar terms, lunar new year)
- model/                   — exported data structures (chart, pillar, life cycle, solar terms)
- internal/
– fourpillars/         — core “Four Pillars” calculation logic (year, month, day, hour)
– luckpillars/         — “Luck Pillars” / ten-year luck cycle logic
– ultis/               — utility algorithms (Ganzhi, solar-term conversion, life cycles)
Other files
- go.mod, go.sum           — module config
- tests (`*_test.go`)      — unit tests for each package

##### README for architectural insights
- Describes the public API usage (`bazica.GetBaziChart`)
- Emphasizes manual JSON data copying for the `data` folder
- Mentions supported date range and external domain knowledge sources

##### Main components
A. Client / Consumer
- Any Go program that imports `github.com/tommitoan/bazica` and calls `GetBaziChart`
B. Public API Layer
- get_bazi_chart.go → exposes `GetBaziChart(now time.Time, loc *time.Location, gender int) (Chart, error)`
C. Domain Logic Layer (internal packages)
1. internal/fourpillars
- get_four_pillars.go
- get_pillar_{year,month,day,hour}.go
2. internal/luckpillars
- get_luck_pillars.go
3. internal/ultis
- Ganzhi conversion, solar-term lookup, life-cycle boundaries
D. Data Layer
- JSON files in /data (lunar-new-year.json, solar-term.json)
- Read by util functions to map calendar dates to stems/branches
E. Model Layer
- model/model_*.go defines strongly typed structs for Chart, Pillar, LifeCycle, SolarTerm

##### Relationships and data flow
1. Client calls → Public API (`GetBaziChart`)
2. API orchestrates:
a. Load raw JSON data via util functions
b. Compute Four Pillars (year, month, day, hour)
c. Compute Luck Pillars (ten-year cycles)
d. Assemble results into Model structs
3. Return populated `Chart` struct to client

##### Architectural patterns and principles
- Layered architecture: clear separation between Public API → Domain logic → Data → Models
- Package encapsulation: all core logic in `internal/`, preventing external misuse
- Single responsibility: each package has one focus (e.g., four-pillar, luck-pillar, utils)
- Test coverage: each package has corresponding `_test.go` for unit tests

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client / Consumer"]:::client
    subgraph "Go Library: bazica"
        subgraph "Public API Layer"
            API["GetBaziChart()"]:::api
        end
        subgraph "Domain Logic Layer"
            subgraph "FourPillars Module"
                FPMain["get_four_pillars.go"]:::file
                FPYear["get_pillar_year.go"]:::file
                FPMon["get_pillar_month.go"]:::file
                FPDay["get_pillar_day.go"]:::file
                FPHour["get_pillar_hour.go"]:::file
            end
            subgraph "LuckPillars Module"
                LPMain["get_luck_pillars.go"]:::file
            end
            subgraph "Utils Module"
                U1["get_ganzhi.go"]:::file
                U2["get_solar-term.go"]:::file
                U3["get_life_cycle.go"]:::file
                U4["ultis.go"]:::file
            end
        end
        subgraph "Data Layer"
            Data(("JSON Data Store")):::data
            Data --> NY["lunar-new-year.json"]:::datafile
            Data --> ST["solar-term.json"]:::datafile
        end
        subgraph "Model Layer"
            M1["model.go"]:::file
            M2["model_bazi-chart.go"]:::file
            M3["model_pillar.go"]:::file
            M4["model_life-cycle.go"]:::file
            M5["model_solar-terms.go"]:::file
        end
    end

    Client -->|"calls"| API
    API -->|"compute Four Pillars"| FPMain
    API -->|"compute Luck Pillars"| LPMain
    API -->|"use utils"| U1
    FPMain -->|"calls utils"| U1
    FPYear -->|"calls utils"| U1
    FPMon -->|"calls utils"| U2
    FPDay -->|"calls utils"| U2
    FPHour -->|"calls utils"| U3
    LPMain -->|"calls utils"| U3
    U1 -->|"reads JSON"| Data
    U2 -->|"reads JSON"| Data
    U3 -->|"reads JSON"| Data
    API -->|"assemble Chart"| M1
    M1 -->|"return Chart"| Client

    click API "https://github.com/tommitoan/bazica/blob/master/get_bazi_chart.go"
    click FPMain "https://github.com/tommitoan/bazica/blob/master/internal/fourpillars/get_four_pillars.go"
    click FPYear "https://github.com/tommitoan/bazica/blob/master/internal/fourpillars/get_pillar_year.go"
    click FPMon "https://github.com/tommitoan/bazica/blob/master/internal/fourpillars/get_pillar_month.go"
    click FPDay "https://github.com/tommitoan/bazica/blob/master/internal/fourpillars/get_pillar_day.go"
    click FPHour "https://github.com/tommitoan/bazica/blob/master/internal/fourpillars/get_pillar_hour.go"
    click LPMain "https://github.com/tommitoan/bazica/blob/master/internal/luckpillars/get_luck_pillars.go"
    click U1 "https://github.com/tommitoan/bazica/blob/master/internal/ultis/get_ganzhi.go"
    click U2 "https://github.com/tommitoan/bazica/blob/master/internal/ultis/get_solar-term.go"
    click U3 "https://github.com/tommitoan/bazica/blob/master/internal/ultis/get_life_cycle.go"
    click U4 "https://github.com/tommitoan/bazica/blob/master/internal/ultis/ultis.go"
    click NY "https://github.com/tommitoan/bazica/blob/master/data/lunar-new-year.json"
    click ST "https://github.com/tommitoan/bazica/blob/master/data/solar-term.json"
    click M1 "https://github.com/tommitoan/bazica/blob/master/model/model.go"
    click M2 "https://github.com/tommitoan/bazica/blob/master/model/model_bazi-chart.go"
    click M3 "https://github.com/tommitoan/bazica/blob/master/model/model_pillar.go"
    click M4 "https://github.com/tommitoan/bazica/blob/master/model/model_life-cycle.go"
    click M5 "https://github.com/tommitoan/bazica/blob/master/model/model_solar-terms.go"

    classDef client fill:#FFCC80,stroke:#E65100;
    classDef api fill:#BBDEFB,stroke:#0D47A1;
    classDef file fill:#E3F2FD,stroke:#0D47A1;
    classDef data fill:#C8E6C9,stroke:#2E7D32;
    classDef datafile fill:#A5D6A7,stroke:#2E7D32;
    classDef model fill:#E3F2FD,stroke:#0D47A1;
```
