# opn48/cnlunar architecture

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

- Interactive diagram: https://gitdiagram.com/opn48/cnlunar
- Repository: https://github.com/opn48/cnlunar

## Overview

cnlunar is a dependency-light Python calendar and almanac library. The user supplies a datetime and initializes `Lunar`; the object computes lunar-calendar and solar-term values, then exposes traditional almanac, holiday, and supplementary calendar information. The README identifies `lunar.py` as the core and documents capabilities beyond the sampled excerpts; those are represented as responsibilities of that core, not as independently verified modules. No external services or database are part of the runtime.

Main entry points: [`cnlunar/lunar.py`](https://github.com/opn48/cnlunar/blob/master/cnlunar/lunar.py) (Lunar API), [`cnlunar/solar24.py`](https://github.com/opn48/cnlunar/blob/master/cnlunar/solar24.py) (Solar terms), [`cnlunar/config.py`](https://github.com/opn48/cnlunar/blob/master/cnlunar/config.py) (Calendar data), [`cnlunar/holidays.py`](https://github.com/opn48/cnlunar/blob/master/cnlunar/holidays.py) (Holiday lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_calendar["Calendar calculations"]
  node_lunar["Lunar API<br/>[lunar.py]"]
  node_dateconvert["Lunar conversion<br/>[lunar.py]"]
  node_terms["Solar terms<br/>[solar24.py]"]
end

subgraph group_almanac["Almanac features"]
  node_traditional["Traditional almanac<br/>[lunar.py]"]
  node_holidays["Holiday lookup<br/>[holidays.py]"]
  node_western["Western calendar<br/>[lunar.py]"]
end

subgraph group_support["Data and utilities"]
  node_config["Calendar data<br/>[config.py]"]
  node_tools["Data utilities<br/>[tools.py]"]
end

node_user(("Library user"))

node_user -->|"initializes"| node_lunar
node_lunar -->|"computes"| node_dateconvert
node_lunar -->|"gets terms"| node_terms
node_lunar -->|"computes"| node_traditional
node_lunar -->|"looks up"| node_holidays
node_lunar -->|"computes"| node_western
node_dateconvert -->|"reads data"| node_config
node_terms -->|"reads data"| node_config
node_terms -->|"uses"| node_tools

click node_lunar "https://github.com/opn48/cnlunar/blob/master/cnlunar/lunar.py"
click node_dateconvert "https://github.com/opn48/cnlunar/blob/master/cnlunar/lunar.py"
click node_terms "https://github.com/opn48/cnlunar/blob/master/cnlunar/solar24.py"
click node_traditional "https://github.com/opn48/cnlunar/blob/master/cnlunar/lunar.py"
click node_holidays "https://github.com/opn48/cnlunar/blob/master/cnlunar/holidays.py"
click node_western "https://github.com/opn48/cnlunar/blob/master/cnlunar/lunar.py"
click node_config "https://github.com/opn48/cnlunar/blob/master/cnlunar/config.py"
click node_tools "https://github.com/opn48/cnlunar/blob/master/cnlunar/tools.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_lunar,node_dateconvert,node_terms,node_user toneBlue
class node_traditional,node_holidays,node_western toneAmber
class node_config,node_tools toneMint
```

## Components

### Calendar calculations

- [Lunar API](https://github.com/opn48/cnlunar/blob/master/cnlunar/lunar.py): `cnlunar/lunar.py`
- [Lunar conversion](https://github.com/opn48/cnlunar/blob/master/cnlunar/lunar.py): `cnlunar/lunar.py`
- [Solar terms](https://github.com/opn48/cnlunar/blob/master/cnlunar/solar24.py): `cnlunar/solar24.py`

### Almanac features

- [Traditional almanac](https://github.com/opn48/cnlunar/blob/master/cnlunar/lunar.py): `cnlunar/lunar.py`
- [Holiday lookup](https://github.com/opn48/cnlunar/blob/master/cnlunar/holidays.py): `cnlunar/holidays.py`
- [Western calendar](https://github.com/opn48/cnlunar/blob/master/cnlunar/lunar.py): `cnlunar/lunar.py`

### Data and utilities

- [Calendar data](https://github.com/opn48/cnlunar/blob/master/cnlunar/config.py): `cnlunar/config.py`
- [Data utilities](https://github.com/opn48/cnlunar/blob/master/cnlunar/tools.py): `cnlunar/tools.py`

### Other components

- **Library user**

## Connections

- Library user → Lunar API: initializes
- Lunar API → Lunar conversion: computes
- Lunar API → Solar terms: gets terms
- Lunar API → Traditional almanac: computes
- Lunar API → Holiday lookup: looks up
- Lunar API → Western calendar: computes
- Lunar conversion → Calendar data: reads data
- Solar terms → Calendar data: reads data
- Solar terms → Data utilities: uses