Wiseman (智者) - Daily Cosmic Reading in Mandarin

📋 Project Overview & Problem Statement

Challenge: Chinese-speaking users interested in spiritual and astrological guidance often need to consult multiple systems separately — Bazi charts, Western horoscopes, Chinese zodiac, and planetary astrology all use different frameworks and vocabulary. Synthesizing them into daily actionable guidance requires specialized knowledge most apps don't provide.

Solution: Wiseman (智者) is a personal daily reading app that runs locally and generates one unified reading per day in plain, conversational Mandarin. It calls Claude Opus five times — once per divination system plus one synthesis — and presents the results in a five-panel dashboard. Once generated, the reading is cached and loads instantly for the rest of the day.

Key Benefits

Four Systems in One: 八字命理, 星座运势, 行星天象, and 生肖运势 synthesized into a single coherent daily outlook
Personalized to You: All readings are grounded in your specific birth date, birth time, Western sign, and Chinese zodiac
Daily Cache: One reading generated per day — consistent, fast, and credible. Reloading the page shows the same reading instantly
Two-Layer Format: Each panel shows both the universal energy (天象宏观) and what it means specifically for you (个人解读)
Floating Chat: Ask Wiseman follow-up questions in Mandarin at any time — he has full context of today's reading
Session Archive: Past readings saved as daily JSON files in the runs/ folder — review any previous day

🖥️ The Five-Panel Dashboard

Panel	System	What It Shows
✦ 今日综合解读	Synthesis	Wiseman's unified take on today — combining all 4 systems into one clear daily message
🀄 八字命理	Bazi / Four Pillars	Day pillar calculation and how today's heavenly stem and earthly branch interact with your birth chart
♌ 星座运势	Western Horoscope	Your daily zodiac reading — general energy for your sign plus personal interpretation
🪐 行星天象	Planetary Astrology	Moon phase, Mercury status, Venus/Mars positions, and seasonal energetic themes
🐓 生肖运势	Chinese Zodiac	How your zodiac animal interacts with today's earthly branch — compatibility, warnings, and opportunities

Each panel has two sections: 天象宏观 (grey — what's happening universally today) and 个人解读 (gold — what it means specifically for you).

📊 Key Metrics

5

Dashboard Panels

5×

Claude API Calls/Day

1/day

Reading Generated

Instant

Reload Speed (cached)

🛠️ Tech Stack & Architecture

Node.js Express Claude Opus API ESM Modules Vanilla JS dotenv Daily JSON Cache

Wiseman runs as a local Node.js server. On first access of the day, it calls the Claude Opus API five times in parallel — once per divination system, then once more for the synthesis panel. Results are saved to runs/YYYY-MM-DD.json and served instantly on all subsequent page loads that day. Personal profile (birthday, birth time, zodiac signs) is stored in wiseman.config.mjs.

Quick Start

# 1. Copy .env.example to .env and add your Claude API key
ANTHROPIC_API_KEY=sk-ant-your-key-here

# 2. Edit wiseman.config.mjs with your birth details

# 3. Double-click start.bat (Windows)
# Browser opens at http://localhost:3000
# First reading takes 20-40 seconds — subsequent loads are instant
            

💡 Design Principles

One reading per day: The daily cache creates credibility. The reading doesn't change every time you refresh — it's your reading for the day, like a newspaper horoscope but personalized.
Plain Mandarin: All output is written in conversational, everyday Mandarin — not classical Chinese. The goal is clarity, not mysticism.
Two-layer structure: Separating the universal (天象宏观) from the personal (个人解读) helps users understand which insights apply to everyone and which apply specifically to them.
Local-first privacy: Only your birth details and today's date are sent to the Claude API. All readings are stored locally.