DOCSEARCHbyAlgolia
Submit Docs

fate (天命之名)

repository·main·Indexed 25 days ago

https://github.com/babyname/fate

An intelligent naming engine that generates and scores names using Bazi (Eight Characters), Five Elements, Wuge numerology, and Zhouyi hexagrams. It is available as a high-performance Go library (v4) and a web-based interface, featuring a five-dimensional scoring system covering cultural impression, Bazi, zodiac, numerology, and phonology.

Tokens
65.7K
Snippets
151
Records
332
Agent score
81%

What's inside fate

  1. Overview of the naming module

    main
    The naming module is the name recommendation engine for the fate project. It is responsible for filtering names based on Five Elements (Wuxing) preferences, scoring names across multiple dimensions (Five Elements, stroke count, and phonology), and generating lists of recommended names.

  2. Overview of fate user scenarios

    main

    The fate service supports four primary user types, each with distinct needs and usage frequencies:

    User TypeScenario DescriptionCore NeedsFrequency
    Newborn ParentsNaming a newbornScientific naming, fast recommendations, understanding the basisHigh
    Name Change SeekersAdults changing namesAnalyzing current names, recommending new namesMedium
    Enterprise ServicesBulk naming servicesHigh efficiency, standardization, low costMedium
    Third-party DevelopersAPI integrationStable APIs, complete documentation, easy integrationLow

  3. Overview of the analysis module deliverables

    main

    The analysis module is responsible for generating formatted outputs for BaZi (Eight Characters), Five Elements (Wuxing), and name recommendations. The module provides data in multiple formats to support different consumer needs.

    Key deliverables include:

    • Go implementation of the analysis logic.
    • JSON output format for programmatic consumption.
    • HTML output format for web-based presentation.
    • Scoring charts for visual data representation.

  4. Understand the fate project directory structure

    main

    The fate project is organized into several layers: an entry layer (cmd), a configuration layer (config), a public API/utility layer (dict, log), an internal implementation layer (internal), and an ORM layer (ent).

    • cmd/: Contains CLI command entry points like console (interactive naming), character (character management), and seeddb (database seeding).
    • config/: Manages configuration loading (YAML), database settings, and logging settings.
    • dict/: A public package for managing character data (CharEntry) and building in-memory indices (DictIndex).
    • log/: A public logging utility providing a Logger interface and file-based implementations.
    • internal/: Contains the core logic that is not importable by external packages. This includes bazi (BaZi calculations), wuxing (Five Elements), wuge (Five Grids), zhouyi (I Ching), naming (recommendation logic), and repository (data access).
    • ent/: Contains auto-generated code from the Ent ORM based on schemas like character.go and wu_xing.go.
    • fate.go: The primary public API entry point for the project, exposing types like Fate, Session, and NameResult.

  5. Review the fate technology stack overview

    main

    The fate project uses the following core technology stack:

    TechnologyVersionPurposeNotes
    Go1.25.0+Primary languageHigh performance, strong concurrency, fast compilation
    chronos/v2v2.0.7+Eight-character (Bazi) calculation libraryWraps lunar-go, provides FateData
    yiv1.0.2+I Ching (Zhouyi) dataSixty-four hexagram data
    sqlite3ent/sqlite3v1.50.0+SQLite driverPure Go, CGO_ENABLED=0
    YAML/JSON1.2Configuration filesParameter management
    Go testingBuilt-inTesting toolsUnit and integration testing

  6. Use the analysis module to format output results

    main
    The analysis module is the output formatting layer of the fate project. It is responsible for transforming raw calculation data into human-readable strings. Use this module to generate formatted Bazi (Eight Characters) analysis, Wuxing (Five Elements) preference reports, and name recommendation lists.

  7. Understand the terminology used in fate

    main

    The fate project uses a specific set of terminology divided into five categories: Basic, Five Elements (Wuxing), Ten Gods (Shishen), Other, and Project-specific terms. Understanding these is essential for interpreting calculation results and interacting with the API.

    Terminology Categories

    CategoryKey Terms
    Basic (基础术语)八字 (Bazi), 四柱 (Four Pillars), 天干 (Heavenly Stems), 地支 (Earthly Branches), 六十甲子 (Sixty Jiazi)
    Five Elements (五行术语)五行 (Five Elements), 五行生克关系 (Generation/Overcoming relationships), 纳音 (Na Yin)
    Ten Gods (十神术语)十神 (Ten Gods), 比肩 (Friend), 劫财 (Rob Wealth), 食神 (Eating God), etc.
    Other (其他术语)藏干 (Hidden Stems), 大运 (Great Cycles), 流年 (Annual Cycles), 旬空 (Void), etc.
    Project (项目术语)FateAPI, FateInput, FateData, BaziInfo, WuxingXijiInfo

  8. Overview of the fate modular layered architecture

    main

    fate uses a modular layered architecture consisting of 5 core modules. The system follows a unidirectional dependency flow where higher-level modules depend on lower-level modules, but lower-level modules remain independent. This design ensures that the system is easy to maintain, test, and extend.

    Dependency Flow: cmd (Entry) → config (Config) → chronos (Calculation) → naming (Recommendation) → analysis (Output)

  9. Overview of the fate core workflow

    main

    The fate core workflow consists of four sequential stages that transform user input into formatted astrological and naming recommendations:

    1. Input Stage: Receives, validates, and preprocesses user parameters.
    2. Calculation Stage (chronos module): Computes Bazi (Eight Characters), Five Elements (Wuxing) preferences, and Great Cycles (Dayun).
    3. Recommendation Stage (naming module): Filters and scores names based on the calculated astrological data.
    4. Output Stage (analysis module): Formats the results into human-readable or machine-readable formats (Text, JSON, HTML).

  10. What is the chronos module and its responsibilities?

    main

    The chronos module is the core calculation engine of the fate project. Its primary purpose is to handle complex astrological and calendar conversions to provide data for naming and analysis tools.

    Core Responsibilities

    • Bazi Calculation: Computing the Four Pillars (Year, Month, Day, Hour), including stems/branches, Five Elements, Na Yin, Ten Gods, hidden stems, and Xun Kong.
    • Five Elements Analysis (Wuxing Xiji): Analyzing the strength of the Day Master to derive preferred (喜用) and avoided (忌神) Five Elements.
    • Data Provision: Serving as the data source for the naming and analysis modules.
    • lunar-go Bridging: Adapting the lunar-go API and converting its output into the project's specific data formats.

    Out-of-Scope (Handled by other modules)

    • Name Filtering: Selecting names based on Five Elements (handled by naming).
    • Name Scoring: Comprehensive name scoring (handled by naming).
    • Output Formatting: Formatting the final Bazi display (handled by analysis).

  11. Understand the fate project package visibility and access rules

    main

    The fate project uses a structured architecture that distinguishes between public APIs and internal implementation details. Developers consuming the library should only interact with the public packages, while internal logic is encapsulated within internal/ directories to prevent external dependency on unstable implementation details.

    Public Packages (Accessible to consumers)

    • fate: The root package containing the primary public API.
    • config: Configuration management.
    • dict: Dictionary/data lookup (can be used independently).

    Internal Packages (Not accessible to consumers)

    Packages located under internal/ are private to the project. Attempting to import these from an external module will result in a compilation error. These include:

    • internal/bazi
    • internal/wuxing
    • internal/wuge
    • internal/filter
    • internal/zhouyi
    • internal/rating
    • internal/naming
    • internal/session
    • internal/repository
    • internal/database
    • internal/analysis

  12. Identify when specific fate terms are used in the lifecycle

    main

    The project distinguishes between terms used during the Calculation Phase (internal logic) and the Output Phase (data returned to the user/API).

    Calculation Phase (Internal Logic)

    These terms are used to derive the core astrological data:

    • Basic Terms: 八字 (Bazi), 天干 (Heavenly Stems), 地支 (Earthly Branches), and 六十甲子 (Sixty Jiazi) are used to calculate the Four Pillars.
    • Five Elements: 五行 (Five Elements) and 五行生克关系 (Generation/Overcoming relationships) are used for analyzing elemental preferences (喜忌).

    Output Phase (API/Result Data)

    These terms represent the data structures and values you will receive in the results:

    • Five Elements: 纳音 (Na Yin).
    • Ten Gods: 十神 (Ten Gods).
    • Other Metadata: 藏干 (Hidden Stems), 大运 (Great Cycles), 流年/流月 (Annual/Monthly Cycles), 旬空 (Void), 命宫/身宫 (Life/Body Palaces), 胎元/胎息 (Fetal/Breath), and 长生十二神 (Twelve Life Stages).