RxLunar

Introduction

Over the past few months, I kept asking myself: Is there a Progressive Web App (PWA) I could build that fulfills a personal need?

• The answer came from a memory a few years back.
• My mother asked if there was a simple lunar calendar app to quickly check when 初一 (the 1st day of the lunar month) or 十五 (the 15th day) falls.
• There were also times when our family wanted to check whether a specific date was auspicious for certain activities.

While numerous traditional Chinese almanac (黄历) apps exist, most are heavily cluttered with intrusive ads.

• To solve this, I decided to build a clean, ad-free PWA: RxLunar.

Lunar Calendar & Almanac Logic

Much of the data in a traditional Chinese almanac relies on astronomical algorithms to compute solar terms, lunar phases, and daily auspiciousness (宜忌).

• Initially, implementing these calculations from scratch felt like a daunting task.
• Fortunately, I discovered the lunar-javascript npm package, which handles lunar date conversions and almanac data client-side with minimal latency.

With the core logic handled, I was able to focus heavily on the user experience (UX).

• During the design phase, I even consulted Gemini to help structure a clear, beginner-friendly guide explaining how to interpret traditional almanac readings.

Fortune Telling

Next, I explored another interesting aspect of Chinese fortune-telling: Four Pillars of Destiny (生辰八字), Bone Weight Astrology (称骨论命), and Purple Star Astrology (紫微斗数).

The calculation logic for 生辰八字 and 称骨论命 also relies on the lunar-javascript package.

• However, even after refining my prompts, I noticed discrepancies between the male and female versions of the poetic verses (歌诀) generated by the AI.
• To resolve this, I ran multiple iterations with the AI to rigorously verify both the underlying calculation logic and the verses themselves, ensuring a much higher degree of accuracy.

For 紫微斗数, I utilized the iztro library.

• This made the process of generating the 12 Palaces of the destiny chart (命盘十二宫) both accurate and complete, saving me from having to rely on AI to build the complex underlying logic from scratch.

The exercise of creating a user guide for these interpretations certainly brought me closer to understanding Chinese traditions, although extracting and interpreting meaningful insights from an astrological chart (八字盘面) proved to be quite complex for an outsider.

Weather API Integration

Finally, I wanted to integrate a reliable weather service.

• I used to rely on The Weather Channel app, but it eventually became bogged down with ads.
• While the native iOS Weather app is reliable, I wanted hands-on experience fetching and handling third-party API data within my own PWA.

I chose Open-Meteo, which provides a generous free tier for non-commercial use:

• 600 calls/minute
• 5,000 calls/hour
• 10,000 calls/day
• 300,000 calls/month

During integration, I tackled a few subtle edge cases - such as resolving time zone offsets when querying distant locations, and filtering hourly precipitation forecasts relative to the user's current local time rather than local midnight.

Summary

Overall, building RxLunar was a rewarding experience, though it came with a few trade-offs.

• Because the app relies on third-party libraries and external APIs for data processing and weather forecasting, I cannot independently guarantee 100% precision.
• Nevertheless, designing and shipping this app was a fantastic end-to-end learning journey - and a great stepping stone as I think about what to build next.