# hnthap/lunar-calendar-api architecture

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

- Interactive diagram: https://gitdiagram.com/hnthap/lunar-calendar-api
- Repository: https://github.com/hnthap/lunar-calendar-api

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["External Client\n(curl/browser)"]:::external

    %% Configuration
    subgraph "Configuration" 
        ConfigLoader["Config Loader\n(.env, tsconfig.json)"]:::config
    end

    %% HTTP Server Layer
    subgraph "HTTP Server Layer"
        HTTP["HTTP Server\n(src/index.ts)"]:::httpLayer
    end

    %% Routing Layer
    subgraph "Routing Layer"
        ConvertRouter["convert.router.ts"]:::routing
        RouterHelp["help.router.ts"]:::routing
    end

    %% Service Layer
    subgraph "Business/Conversion Service"
        ConversionService["Conversion Service\n(orchestration)"]:::service
    end

    %% Algorithm Modules
    subgraph "Algorithm Modules"
        Chinese["Chinese.ts"]:::service
        Gregorian["Gregorian.ts"]:::service
        Lunar["Lunar.ts"]:::service
        Algorithms["algorithms.ts"]:::service
        Constants["constants.ts"]:::service
        UtilsHelper["utils.ts"]:::service
    end

    %% Type Definitions
    subgraph "Type Definitions"
        CalendarTypes["calendar.ts"]:::config
        LanguageTypes["language.ts"]:::config
    end

    %% Test Suite
    subgraph "Test Suite"
        Tests["lunar.test.ts"]:::tests
    end

    %% Data Flow
    Client -->|"HTTP request"| HTTP
    ConfigLoader -->|loads env| HTTP
    HTTP -->|"GET /convert request"| ConvertRouter
    HTTP -->|"GET /help request"| RouterHelp
    ConvertRouter -->|"validate & orchestrate"| ConversionService
    ConversionService -->|"uses logic"| Chinese
    ConversionService -->|"uses logic"| Gregorian
    ConversionService -->|"uses logic"| Lunar
    ConversionService -->|"calls core math"| Algorithms
    ConversionService -->|"reads constants"| Constants
    ConversionService -->|"uses helpers"| UtilsHelper
    ConversionService -->|"needs types"| CalendarTypes
    ConversionService -->|"needs types"| LanguageTypes
    ConversionService -->|returns result| ConvertRouter
    ConvertRouter -->|"JSON response"| HTTP
    Tests -->|"unit tests call"| Chinese
    Tests -->|"unit tests call"| Gregorian
    Tests -->|"unit tests call"| Lunar
    Tests -->|"unit tests call"| Algorithms
    Tests -->|"unit tests call"| Constants
    Tests -->|"unit tests call"| UtilsHelper

    %% Click Events
    click HTTP "https://github.com/hnthap/lunar-calendar-api/blob/main/src/index.ts"
    click ConvertRouter "https://github.com/hnthap/lunar-calendar-api/blob/main/src/routers/convert.router.ts"
    click RouterHelp "https://github.com/hnthap/lunar-calendar-api/blob/main/src/routers/help.router.ts"
    click ConversionService "https://github.com/hnthap/lunar-calendar-api/blob/main/src/routers/convert.router.ts"
    click Chinese "https://github.com/hnthap/lunar-calendar-api/blob/main/src/utils/Chinese.ts"
    click Gregorian "https://github.com/hnthap/lunar-calendar-api/blob/main/src/utils/Gregorian.ts"
    click Lunar "https://github.com/hnthap/lunar-calendar-api/blob/main/src/utils/Lunar.ts"
    click Algorithms "https://github.com/hnthap/lunar-calendar-api/blob/main/src/utils/algorithms.ts"
    click Constants "https://github.com/hnthap/lunar-calendar-api/blob/main/src/utils/constants.ts"
    click UtilsHelper "https://github.com/hnthap/lunar-calendar-api/blob/main/src/utils/utils.ts"
    click CalendarTypes "https://github.com/hnthap/lunar-calendar-api/blob/main/src/types/calendar.ts"
    click LanguageTypes "https://github.com/hnthap/lunar-calendar-api/blob/main/src/types/language.ts"
    click Tests "https://github.com/hnthap/lunar-calendar-api/blob/main/tests/lunar.test.ts"

    %% Styles
    classDef httpLayer fill:#D0E7FF,stroke:#0B69A3;
    classDef routing fill:#AED6F1,stroke:#2874A6;
    classDef service fill:#D5F5E3,stroke:#229954;
    classDef config fill:#FCF3CF,stroke:#B7950B;
    classDef tests fill:#E5E8E8,stroke:#797D7F;
    classDef external fill:#F2F3F4,stroke:#ABB2B9;
```
