Building QiLoom: Calendar Conversion Is a Domain Modeling Problem

I’m building QiLoom, a free website for Gregorian and Chinese lunar calendar conversion, birthday lookup, zodiac lookup, completed age, and family milestones.

The interesting engineering problem isn’t the date picker. It’s deciding exactly what a date represents.

A scope note before the technical discussion: I’m not publishing a framework, hosting, or dependency inventory here. The useful part of this write-up is the domain model and the implementation questions it creates, not an invented stack tour.

A calendar date is not automatically a timestamp

A birthday is usually a civil date, not an instant.

That distinction matters in JavaScript. Moving a date through UTC serialization and local rendering can introduce a day shift that has nothing to do with the calculation the user requested.

For this kind of tool, I favor reasoning about year, month, and day as explicit components. Time zones should enter the model only when the operation actually requires them.

Lunar dates need more than three numbers

A Chinese lunar date needs calendar context, including whether the month is a leap month.

Conceptually, the input looks more like this:

type LunarDate = {
  year: number;
  month: number;
  day: number;
  isLeapMonth: boolean;
};

This is an illustrative model, not an extract from the production code.

The important point is that dropping isLeapMonth can discard information. A UI that hides that distinction can make an otherwise plausible calculation ambiguous.

Similar-looking calculations need separate contracts

Completed age, elapsed days, and a baby’s hundredth day are different operations.

Completed age depends on whether the birthday has occurred in the reference year. Date intervals require an explicit inclusion convention. A milestone calculation needs to explain how the birth date is counted.

I’d rather have small, separately testable domain functions than one generic helper with a growing collection of boolean flags.

Test the boundaries, not just the happy path

The test cases I care about include lunar new year boundaries, leap months, Gregorian leap days, month transitions, and birthdays close to the reference date.

Round-trip conversion checks are useful too, but they should complement comparison against trusted calendar references—not replace it.

Try QiLoom and tell me which assumptions the interface should expose more clearly. I’m especially interested in how other developers communicate calendar conventions without overwhelming the form.