Meihuaapp

💡 Inspiration

Inspired by Shao Yong's Meihua Yishu (Plum Blossom Numerology), a classical Chinese divination system that encodes the Yijing's philosophical framework into precise mathematics.

The core idea: divination is not magic — it's a deterministic algorithm mapping numbers through trigrams and hexagrams via modular arithmetic and five-element relations. We wanted to make every step of that algorithm visible, so anyone can understand why the app gives the answer it does, starting from first principles.

⚙️ What it does

Meihuaapp is a local-first Android app that performs full Meihua Yishu divination using three input methods (current time, manual number entry, or random), then walks the user through all 10 algorithmic steps:

1. Upper Trigram (上卦)
2. Lower Trigram (下卦)
3. Moving Line (动爻)
4. Original Hexagram (本卦)
5. Mutual Hexagram (互卦)
6. Changed Hexagram (变卦)
7. Body-Use Analysis (体用分析)
8. Five-Element Relation (五行生克)
9. Moving-Line Text (爻辞)
10. Synthesized Judgment (综合断语)

Every step shows the raw formula, intermediate values, result, and a beginner-friendly explanation. It supports both an auto-advancing guide mode and a one-shot summary mode.

🛠️ How we built it

• Tech Stack: Pure Kotlin + Jetpack Compose with a strict decoupled architecture.
• Core Engine: A pure-function pipeline engine (10 composable stateless steps).
• Storage: A Room SQLite persistence layer.
• UI Layer: A clean Compose UI with three main tabs: Divination, History, and Settings.
• Data Assets: All 64 hexagrams (including judgment, image text, and 6 line texts each from the Wang Bi recension) are bundled as JSON assets and imported into Room on first launch.
• Lunar Calendar: Conversion uses a pre-computed lookup table.
• Privacy: No network calls, no telemetry — entirely local-first.

🚧 Challenges we ran into

• Mathematical Precision: The fundamental challenge was getting every mathematical detail right under adversarial review:
  • The exact formula for time-based divination: $$\text{Upper Trigram} = (\text{Year-Branch} + \text{Lunar Month} + \text{Lunar Day}) \pmod 8$$ $$\text{Lower Trigram} = (\text{Year-Branch} + \text{Lunar Month} + \text{Lunar Day} + \text{Hour-Branch}) \pmod 8$$ $$\text{Moving Line} = (\text{Year-Branch} + \text{Lunar Month} + \text{Lunar Day} + \text{Hour-Branch}) \pmod 6$$ (Three input numbers but only two distinct sums).
  • The binary encoding for mutual hexagram derivation (bit shifting the 6-bit hexagram).
  • The five-element generation/restriction cycles.
  • The body/use trigram determination rule (where the moving line position determines which trigram is body vs use).
• Environment Obstacles: Setting up the project on a network-restricted Windows machine required manually caching Gradle 8.2 and configuring a local proxy.

🎉 Accomplishments that we're proud of

• Fully Traceable 10-Step Pipeline: Every intermediate value is exposed as a first-class StepResult with its formula, intermediate calculation, result, and human-readable explanation — not hidden in debug logs, but presented as the primary UI.
• Adversarial Review: This process successfully caught subtle issues (such as missing binary-to-trigram mapping, ambiguous boundary cases, and lunar calendar data volume) before a single line of Kotlin was written.
• Reproducibility: The companion file system in the implementation plan means the entire codebase is fully reproducible from the spec.

🧠 What we learned

• Meihua Yishu is not mystical — it's a finite-state machine over 8 trigrams and 64 hexagrams, with deterministic rules for every transformation.
• The hardest part of building this wasn't the math (which is simple modular arithmetic) but the traceability: designing a data structure that captures not just the result of each step, but the reasoning path that produced it, in a way that a beginner can easily follow.

🔮 What's next for Meihuaapp

• Lunar Calendar Expansion: Complete the lunar calendar data (covering 1900–2100 using real astronomical sources).
• New Input Methods: Add sound, character, and direction input methods once the InputMethod interface is ready.
• Customization: Optionally expose a user-editable hexagram text database for personalized interpretation.
• Extensibility: The architecture is designed for extension — the pipeline engine doesn't care where the input numbers come from, as long as they arrive as a Triple<Int, Int, Int>.

Built With

• codex