# manche123/solar-lunar-converter architecture

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

- Interactive diagram: https://gitdiagram.com/manche123/solar-lunar-converter
- Repository: https://github.com/manche123/solar-lunar-converter

## Overview

##### Project Type and Purpose
- This is an open-source, Python-based Solar-Lunar calendar conversion tool.
- It exposes its core logic as a library (`accurate_lunar_converter.py`) and provides two CLI front-ends: `interactive_converter.py` (interactive shell) and `example.py` (scripted usage).
- Its primary function is to convert a `datetime` object into detailed lunar calendar data (干支, 节气, 闰月, 时辰) by leveraging the external `zhdate` library.

##### File-Structure Analysis
Top-level files:
- .gitignore
- README.md
- requirements.txt
- accurate_lunar_converter.py   ← core library
- example.py                    ← example script showing library usage
- interactive_converter.py      ← CLI interactive tool

Patterns/Implications:
- Single-module library + two CLI wrappers
- Dependencies declared in requirements.txt (`zhdate`)
- No separate “backend” or “frontend” directories—this is a utility library with CLI interfaces.

##### Key README Insights
- Describes functional scope: conversion, 干支 calculations, 节气判断, 闰月处理, 时辰转换
- Mentions using `zhdate` for accuracy
- Lists input/output formats and usage examples
- Notes possible extension points (e.g., more precise astronomical algorithms)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Interfaces
    User(["User"]):::external
    InteractiveCLI["interactive_converter CLI"]:::cli
    ExampleCLI["example.py CLI"]:::cli

    User --> InteractiveCLI
    User --> ExampleCLI

    %% Core Converter Entry
    Converter["AccurateLunarConverter"]:::core
    InteractiveCLI --> Converter
    ExampleCLI --> Converter
    click InteractiveCLI "https://github.com/manche123/solar-lunar-converter/blob/main/interactive_converter.py"
    click ExampleCLI "https://github.com/manche123/solar-lunar-converter/blob/main/example.py"
    click Converter "https://github.com/manche123/solar-lunar-converter/blob/main/accurate_lunar_converter.py"

    %% Converter Internal Workflow
    subgraph "AccurateLunarConverter Internal"
        direction TB
        Datetime["datetime (stdlib)"]:::external
        InputValidation["Input Validation"]:::core
        ZhdateCall["zhdate API Calls"]:::external
        GanzhiLogic["干支/节气 Logic"]:::core
        OutputFormatter["Output Formatting"]:::core
    end

    Converter --> InputValidation
    Datetime --> InputValidation
    InputValidation --> ZhdateCall
    InputValidation --> GanzhiLogic
    ZhdateCall --> GanzhiLogic
    GanzhiLogic --> OutputFormatter
    OutputFormatter --> ConsoleOutput

    ConsoleOutput["Console Output"]:::external

    %% Project Artifacts
    subgraph "Project Artifacts"
        README["README.md"]:::doc
        Requirements["requirements.txt"]:::external
    end
    click README "https://github.com/manche123/solar-lunar-converter/blob/main/README.md"
    click Requirements "https://github.com/manche123/solar-lunar-converter/blob/main/requirements.txt"

    %% Styling
    classDef cli fill:#D0E8FF,stroke:#0066CC,stroke-width:2px
    classDef core fill:#DFFFE0,stroke:#33AA33,stroke-width:2px
    classDef external fill:#F0F0F0,stroke:#888888,stroke-width:1px,stroke-dasharray: 5 5
    classDef doc fill:#FFF8DC,stroke:#DAA520,stroke-width:2px
```
