# tuletanh/numberology architecture

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

- Interactive diagram: https://gitdiagram.com/tuletanh/numberology
- Repository: https://github.com/tuletanh/numberology

## Overview

This web app takes a person’s birth details and name, then returns a Tử Vi chart and four Pythagorean numerology indicators. Its main workflow runs through the browser and FastAPI, with chart calculation, numerology, and chart-detail retrieval as distinct stages; Cohere optionally turns retrieved context into natural-language interpretations and answers. The README documents lunar-date conversion and the major capabilities; the sampled excerpts do not show every route or all subsystem wiring, so uncertain links are omitted.

Main entry points: [`main.py`](https://github.com/tuletanh/numberology/blob/main/main.py) (FastAPI API), [`frontend/script.js`](https://github.com/tuletanh/numberology/blob/main/frontend/script.js) (Web client), [`engine_tu_vi.py`](https://github.com/tuletanh/numberology/blob/main/engine_tu_vi.py) (Chart engine), [`lookup_sao.py`](https://github.com/tuletanh/numberology/blob/main/lookup_sao.py) (Star interpretation lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Web interface"]
  node_frontend["Web client<br/>[script.js]"]
  node_api["FastAPI API<br/>[main.py]"]
end

subgraph group_calculation["Chart calculation"]
  node_lunar["Lunar conversion"]
  node_chart_engine["Chart engine<br/>[engine_tu_vi.py]"]
  node_destiny["Mệnh and Cục<br/>[an_menh_cuc.py]"]
  node_minor_stars["Auxiliary stars<br/>[an_phu_tinh.py]"]
  node_four_transformations["Tứ Hóa<br/>[tu_hoa.py]"]
  node_chart_table["Star placement table<br/>[bang_tu_vi.json]"]
end

subgraph group_numerology["Numerology"]
  node_numerology_engine["Numerology engine"]
  node_numerology_data["Numerology lookup data"]
end

subgraph group_interpretation["Interpretation"]
  node_star_lookup["Star interpretation lookup<br/>[lookup_sao.py]"]
  node_star_data["Star meanings"]
  node_cohere_client["Cohere client<br/>[cohere_client.py]"]
end

node_user(("User"))
node_cohere{{"Cohere API"}}

node_user -->|"enters details"| node_frontend
node_frontend -->|"requests chart"| node_api
node_api -->|"converts date"| node_lunar
node_api -->|"calculates chart"| node_chart_engine
node_api -->|"calculates placement"| node_destiny
node_api -->|"calculates stars"| node_minor_stars
node_api -->|"calculates transformations"| node_four_transformations
node_chart_engine -->|"reads placements"| node_chart_table
node_api -->|"calculates indicators"| node_numerology_engine
node_api -->|"requests meanings"| node_star_lookup
node_star_lookup -->|"reads meanings"| node_star_data
node_api -->|"reads interpretations"| node_numerology_data
node_api -->|"sends context"| node_cohere_client
node_cohere_client -->|"calls chat API"| node_cohere
node_api -->|"returns results"| node_frontend
node_frontend -->|"requests details or chat"| node_api

click node_frontend "https://github.com/tuletanh/numberology/blob/main/frontend/script.js"
click node_api "https://github.com/tuletanh/numberology/blob/main/main.py"
click node_chart_engine "https://github.com/tuletanh/numberology/blob/main/engine_tu_vi.py"
click node_destiny "https://github.com/tuletanh/numberology/blob/main/an_menh_cuc.py"
click node_minor_stars "https://github.com/tuletanh/numberology/blob/main/an_phu_tinh.py"
click node_four_transformations "https://github.com/tuletanh/numberology/blob/main/tu_hoa.py"
click node_chart_table "https://github.com/tuletanh/numberology/blob/main/bang_tu_vi.json"
click node_numerology_engine "https://github.com/tuletanh/numberology/blob/main/engine_than_so_hoc.py"
click node_numerology_data "https://github.com/tuletanh/numberology/blob/main/data/than_so_hoc_bang_tra_v2.json"
click node_star_lookup "https://github.com/tuletanh/numberology/blob/main/lookup_sao.py"
click node_star_data "https://github.com/tuletanh/numberology/tree/main/sao_json"
click node_cohere_client "https://github.com/tuletanh/numberology/blob/main/cohere_client.py"

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_frontend,node_api,node_user toneBlue
class node_lunar,node_chart_engine,node_destiny,node_minor_stars,node_four_transformations,node_chart_table toneAmber
class node_numerology_engine,node_numerology_data,node_cohere toneMint
class node_star_lookup,node_star_data,node_cohere_client toneRose
```

## Components

### Web interface

- [Web client](https://github.com/tuletanh/numberology/blob/main/frontend/script.js): `frontend/script.js`
- [FastAPI API](https://github.com/tuletanh/numberology/blob/main/main.py): `main.py`

### Chart calculation

- **Lunar conversion**
- [Chart engine](https://github.com/tuletanh/numberology/blob/main/engine_tu_vi.py): `engine_tu_vi.py`
- [Mệnh and Cục](https://github.com/tuletanh/numberology/blob/main/an_menh_cuc.py): `an_menh_cuc.py`
- [Auxiliary stars](https://github.com/tuletanh/numberology/blob/main/an_phu_tinh.py): `an_phu_tinh.py`
- [Tứ Hóa](https://github.com/tuletanh/numberology/blob/main/tu_hoa.py): `tu_hoa.py`
- [Star placement table](https://github.com/tuletanh/numberology/blob/main/bang_tu_vi.json): `bang_tu_vi.json`

### Numerology

- [Numerology engine](https://github.com/tuletanh/numberology/blob/main/engine_than_so_hoc.py): `engine_than_so_hoc.py`
- [Numerology lookup data](https://github.com/tuletanh/numberology/blob/main/data/than_so_hoc_bang_tra_v2.json): `data/than_so_hoc_bang_tra_v2.json`

### Interpretation

- [Star interpretation lookup](https://github.com/tuletanh/numberology/blob/main/lookup_sao.py): `lookup_sao.py`
- [Star meanings](https://github.com/tuletanh/numberology/tree/main/sao_json): `sao_json`
- [Cohere client](https://github.com/tuletanh/numberology/blob/main/cohere_client.py): `cohere_client.py`

### Other components

- **User**
- **Cohere API**

## Connections

- User → Web client: enters details
- Web client → FastAPI API: requests chart
- FastAPI API → Lunar conversion: converts date
- FastAPI API → Chart engine: calculates chart
- FastAPI API → Mệnh and Cục: calculates placement
- FastAPI API → Auxiliary stars: calculates stars
- FastAPI API → Tứ Hóa: calculates transformations
- Chart engine → Star placement table: reads placements
- FastAPI API → Numerology engine: calculates indicators
- FastAPI API → Star interpretation lookup: requests meanings
- Star interpretation lookup → Star meanings: reads meanings
- FastAPI API → Numerology lookup data: reads interpretations
- FastAPI API → Cohere client: sends context
- Cohere client → Cohere API: calls chat API
- FastAPI API → Web client: returns results
- Web client → FastAPI API: requests details or chat