What I Learned Building an Online I Ching Casting Tool

Tachyon — Sat, 29 Aug 2026 08:19:50 +0000

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.

DEV Community: Tachyon