How hnthap/lunar-calendar-api works
Project type and purpose
• This is a standalone, stateless HTTP API server written in Node.js with TypeScript.
• Its sole purpose is to convert dates between the Gregorian and Lunar calendars using astronomical algorithms.
File structure
• Top-level files:
• package.json / package-lock.json – Node/NPM metadata
• tsconfig.json – TypeScript compiler settings
• .gitignore, LICENSE, README.md
• src/index.ts
• Entrypoint that spins up an Express-like HTTP server
• src/routers
• convert.router.ts – handles GET /convert
• help.router.ts – serves usage/help info
• src/utils
• Chinese.ts, Gregorian.ts, Lunar.ts – calendar-specific logic
• algorithms.ts – core Meeus-based math
• constants.ts – magic numbers (e.g., time-zone offsets)
• utils.ts – shared helper functions
• src/types
• calendar.ts, language.ts – TypeScript interfaces/enums
• tests
• lunar.test.ts – unit tests for core conversion logic
Extract architecture insights from the README
• Server listens on configurable PORT via an .env
• Exposes exactly one conversion endpoint with parameters for source/target, date fields, time zone
• Uses npm scripts for build, start, test
• No external databases or third-party services—pure in-memory algorithmic service
a. Main components
1. External Client (curl, browser, another service)
2. HTTP Server Layer
• Express app (src/index.ts)
• Environment/config loader (.env)
3. Routing Layer
• convert.router – request validation and dispatch
• help.router – usage endpoint
4. Business/Conversion Service
• Orchestrates calls into utils modules
5. Algorithm Modules (src/utils)
• Chinese, Gregorian, Lunar, algorithms, constants, utils
6. Type Definitions (src/types)
7. Test Suite (tests/lunar.test.ts)
b. Relationships and data flow
• Client → HTTP Server → Router → Conversion Service → Algorithm Modules → Service returns result → Router formats JSON → HTTP Server sends response → Client
• Config loader populates environment variables before server start
• Tests invoke algorithm modules directly to validate core logic
c. Architectural patterns and principles
• Layered (Presentation → Routing → Service → Utility)
• Single-responsibility: routers only handle HTTP concerns, utils only handle math
• Separation of concerns: configuration, types, business logic
d. Key technologies
• Node.js runtime, Express or similar minimal HTTP framework
• TypeScript for static typing (tsconfig.json)
• NPM scripts for build (tsc), start (node), test (jest/mocha)