At first, building an online I Ching tool sounded like a fairly small web project.
There are 64 hexagrams. A user performs a cast. The application identifies the result and displays an interpretation.
But while building Quick I Ching, I found that the difficult part was not displaying a hexagram.
The difficult part was deciding which parts of a traditional casting process had to survive the move into software.
That turned into a useful lesson in domain modeling, product design, and the risks of simplifying a system too aggressively.
The final hexagram is not enough
One of the first architectural decisions was to avoid treating a reading as nothing more than a number between 1 and 64.
A cast contains more information than that.
For the traditional line-based methods, six lines are generated. Those lines determine the primary hexagram, but they can also contain changing lines.
If changing lines are present, they transform and produce a relating hexagram.
So the useful state of a reading includes more than:
- “Hexagram 24”
It also needs to preserve things such as:
- the six original line values
- the primary hexagram
- which lines are changing
- the relating hexagram
- the casting method used
That distinction became important very quickly.
If I stored only the final hexagram number, I would have thrown away information that the interface later needed in order to explain the reading properly.
Line order is a domain rule, not a UI detail
An I Ching hexagram is built from the bottom upward.
The first line cast is line 1 at the bottom. The sixth line is at the top.
That sounds like a small implementation detail, but it is actually a domain rule.
The application therefore keeps the six lines in bottom-up order rather than allowing the rendering layer to decide what the order “probably” means.
This was a useful reminder that domain-specific software often breaks in very ordinary places.
A developer can build something that looks visually correct while quietly reversing the meaning of the underlying data.
When the domain has established rules, those rules should be represented explicitly rather than reconstructed later from UI assumptions.
Changing lines need to remain first-class data
Changing lines are another place where an implementation can become too lossy.
A changing yin line becomes yang.
A changing yang line becomes yin.
The transformed lines create the relating hexagram.
For the software, that means the important sequence is not simply:
cast → hexagram
It is closer to:
cast → primary hexagram → identify changing lines → transform them → relating hexagram
The application needs to preserve that relationship all the way through to the result page.
This is why I did not want changing lines to become a small decorative annotation added after the hexagram had already been calculated.
They are part of the result itself.
For users who want the non-technical explanation, I also documented the concept separately in the guide to changing lines.
Different casting methods should remain different
Another design problem appeared when supporting more than one way to cast.
Quick I Ching currently supports traditional methods including the Three-Coin Method, Yarrow Stalk Method, and Mei Hua Yi Shu, alongside a Manual Cast option in the product.
From a UI perspective, it would be tempting to make them all variations of one generic “random hexagram” function.
That would certainly make the application simpler.
It would also be misleading.
The methods do not represent the same process with different labels.
So in the codebase, the casting domain separates the method-specific logic instead of pretending that every method is interchangeable.
There are distinct areas for Three-Coin casting, Yarrow Stalk casting, and Mei Hua Yi Shu, while shared hexagram logic sits separately.
That boundary matters because the application can change or test one casting method without redefining what a hexagram result means everywhere else.
The user-facing explanation of one of these methods is available in the Three-Coin I Ching Method.
Normalize the result, not the tradition
The useful architectural pattern turned out to be:
different inputs → method-specific logic → common result model
The methods can differ, while the rest of the application can still work with a stable representation of a completed cast.
That shared result can describe:
- six lines in their correct order
- the primary hexagram
- moving-line positions
- the relating hexagram when one exists
- which casting method produced the result
This creates a clean boundary between “how the cast is produced” and “what the rest of the application needs to know about the cast.”
I think this is a useful pattern for many domain-heavy products.
Normalization should happen after the important domain-specific behavior, not by erasing those differences at the beginning.
Versioning the algorithm was worth doing
One detail I initially could have treated as unnecessary was algorithm versioning.
The casting result does not only record which method produced it. The domain model also has room for the algorithm version and the classic hexagram mapping version.
That may look excessive for a small tool, but there is a practical reason for it.
If an implementation changes later, a historical result should not become impossible to explain.
Being able to say “this result was produced by this method using this version of the algorithm” makes debugging and future migrations much safer.
It also prevents a subtle class of bugs where the software changes but old saved results silently acquire new meaning.
The lesson here was not “version everything.”
It was:
If an algorithm creates meaningful persisted output, knowing which algorithm created that output can be part of the data.
The interface should simplify work, not erase structure
There is always pressure to make a web tool feel effortless.
For an I Ching product, the most aggressive version of that idea would be:
click once → receive an answer
But that removes almost everything that distinguishes an actual cast from a generic random result.
I wanted the interface to reduce mechanical work while still making the important structure visible.
A user should still be able to understand:
- how the cast was produced
- what the six lines are
- which lines are changing
- which hexagram is primary
- whether a relating hexagram exists
The computer can do the bookkeeping.
It does not need to hide the system.
That became one of the main product principles behind Quick I Ching:
Simplify the work, not the underlying model.
Domain modeling matters even in a small product
Quick I Ching is not an enterprise-scale system.
But building it reinforced something I usually associate with much larger software projects:
good domain boundaries matter even when the product is small.
If I had modeled a reading as only a hexagram number, almost every later feature involving changing lines, relating hexagrams, different methods, or reproducibility would have required reconstructing information that had already been discarded.
Preserving the meaningful state made the rest of the product easier to reason about.
It also made the implementation closer to the thing it was trying to represent.
That is probably the main engineering lesson I took from building Quick I Ching:
When digitizing a traditional system, simplify the interaction — not the rules that give the system its meaning.