How vsme/chinese-days works
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.