# vsme/chinese-days architecture

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

- Interactive diagram: https://gitdiagram.com/vsme/chinese-days
- Repository: https://github.com/vsme/chinese-days

## Overview

##### Main Components
- Core Logic Modules:
- Holidays: Handles definitions, arrangements, and generation of holiday data (src/holidays).
- Solar Terms: Manages the 24 solar terms calculations (src/solar_terms).
- Lunar and Solar Conversions: Contains logic for converting between lunar and solar dates (src/solar_lunar).
- Lunar Folk Festival: Contains functions and constants related to traditional festivals on the lunar calendar (src/lunar_folk_festival).
- Utilities: Provides supporting utility functions (src/utils), e.g., for date operations.
- Scripts:
- Build Scripts: Scripts for building output files such as ICS (scripts/build-ics.ts) and JSON (scripts/build-json.ts).
- Data Fetch: Script for fetching any external data (scripts/fetch.ts).
- Testing:
- Unit Tests: Organized by module (test/holidays, test/solar_terms, etc.) to validate functionalities.
- Documentation:
- Docs: Contains Vitepress configuration, custom themes, and content (docs/), supporting both Chinese and English languages.
- Continuous Integration/Deployment:
- GitHub Workflows: Automated testing, deployment for docs, publishing, and sending emails upon updates.

##### Relationships and Interactions
- The core modules in the src folder are the heart of the library. They interact with each other where necessary (for example, holiday calculations may depend on the solar/lunar conversion functions).
- The utility functions support various modules across the project.
- The build scripts (under scripts) use the core modules to generate iCal files (holidays.ics and holidays.en.ics) and JSON files, making the data consumable for external clients.
- The testing suite runs unit tests that verify each module in src; tests are organized parallel to the modules to ensure comprehensive coverage.
- The documentation system pulls examples and API information from the source and is continuously deployed using GitHub workflows.
- GitHub Actions (in .github/workflows) orchestrate automated tasks such as running tests, building documentation, publishing releases, and sending email notifications when holiday data is updated.

##### Architectural Patterns and Design Principles
- Modular Design: The project separates concerns distinctly by placing different business logic in separate subdirectories (holidays, lunar_folk_festival, solar_lunar, solar_terms), which supports high cohesion and low coupling.
- Automation: CI/CD pipelines ensure the integrity of the build, testing, and deployment process.
- Extensibility and Reusability: Each module is self-contained, meaning future holiday types or calendar conversion features can be added without major refactoring.
- Test-Driven Development: A comprehensive test suite is provided to ensure code quality and reliability.

##### Final Touches
- Clarity by minimizing overlap: separate each architectural layer (Domain Logic, Supporting Tools, and Infrastructure).
- Each module’s role.
- External interactions (e.g., data subscriptions for iCal).
- Automation and testing workflows.
- Verify that all elements match the project structure provided by the file tree and supported by the README’s description.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core Business Logic
    subgraph "Core Business Logic"
        H["Holidays"]:::core
        ST["Solar Terms"]:::core
        LS["Lunar and Solar Conversions"]:::core
        LFF["Lunar Folk Festival"]:::core
        UT["Utilities"]:::core
    end

    %% Utility Scripts
    subgraph "Utility Scripts"
        ICS["Build Script (iCal)"]:::script
        JSON["Build Script (JSON)"]:::script
        DF["Data Fetch Script"]:::script
    end

    %% Testing Infrastructure
    subgraph "Testing Infrastructure"
        TS["Testing Suite"]:::test
    end

    %% Documentation and Deployment
    subgraph "Documentation and Deployment"
        DOC["Documentation"]:::doc
        CI["CI/CD Workflows"]:::ci
    end

    %% Relationships among components
    H -->|"provides_data"| ICS
    H -->|"provides_data"| JSON
    LS -->|"conversion_support"| H
    UT -->|"utility_support"| H
    UT -->|"utility_support"| ST
    UT -->|"utility_support"| LS
    UT -->|"utility_support"| LFF
    DF -->|"fetches_data_for"| H
    TS -->|"tests"| H
    TS -->|"tests"| ST
    TS -->|"tests"| LS
    TS -->|"tests"| LFF
    TS -->|"tests"| UT
    TS -->|"tests"| ICS
    TS -->|"tests"| JSON
    TS -->|"tests"| DF
    H -->|"documents"| DOC
    ST -->|"documents"| DOC
    LS -->|"documents"| DOC
    LFF -->|"documents"| DOC
    CI -->|"runs_tests"| TS
    CI -->|"deploys_docs"| DOC

    %% Click events for component mapping
    click H "https://github.com/vsme/chinese-days/tree/main/src/holidays"
    click ST "https://github.com/vsme/chinese-days/tree/main/src/solar_terms"
    click LS "https://github.com/vsme/chinese-days/tree/main/src/solar_lunar"
    click LFF "https://github.com/vsme/chinese-days/tree/main/src/lunar_folk_festival"
    click UT "https://github.com/vsme/chinese-days/tree/main/src/utils"
    click ICS "https://github.com/vsme/chinese-days/blob/main/scripts/build-ics.ts"
    click JSON "https://github.com/vsme/chinese-days/blob/main/scripts/build-json.ts"
    click DF "https://github.com/vsme/chinese-days/blob/main/scripts/fetch.ts"
    click TS "https://github.com/vsme/chinese-days/tree/main/test"
    click DOC "https://github.com/vsme/chinese-days/tree/main/docs"
    click CI "https://github.com/vsme/chinese-days/tree/main/.github/workflows"

    %% Styles
    classDef core fill:#f9c,stroke:#333,stroke-width:2px;
    classDef script fill:#ccf,stroke:#333,stroke-width:2px;
    classDef test fill:#cfc,stroke:#333,stroke-width:2px;
    classDef doc fill:#fc9,stroke:#333,stroke-width:2px;
    classDef ci fill:#9cf,stroke:#333,stroke-width:2px;
```
