I Ching Studio

What I built

I Ching Studio is a bilingual English/Mandarin decision product for structured I Ching readings. A session keeps the classical reading, line sources, calendar context, Najia table, AI analysis, follow-up conversation, and user history in one object.

The app uses Next.js with English and Chinese routes. The service layer uses deterministic interpretation retrieval, model capability gating, session history, and a local SQLite corpus that can be regenerated from source texts. This website avoids pinning transient public model names; the live app and its repo remain the source of truth for current runtime configuration.

What is actually implemented

The repo contains a production-shaped app rather than a demo script:

• Frontend: Next.js 16 App Router, React 19, TypeScript, Tailwind, Radix UI, Framer Motion, TanStack Query, Zustand, Supabase auth, bilingual routing.
• Backend: API routes for config, session creation, session listing, chat transcript, follow-up chat, and session deletion.
• Core engine: casting methods for stalk, coin, Meihua, and manual six-line input; BaZi/time handling; hexagram transformation; Najia lookup; result packaging.
• Persistence: Supabase session rows and chat messages, with payload snapshots that let old readings reopen and continue.
• AI controls: model selection, reasoning effort, verbosity, tone, access gate, per-session turn/token limits, and daily user token limits.

Source retrieval layer

The important engineering choice is the retrieval schema. The product first resolves the reading into relevant hexagram and line positions, then assembles deterministic source excerpts before any model response is generated.

The two special use slots are preserved for full-moving Qian and Kun conditions: yong_jiu for Qian and yong_liu for Kun. Tests also verify bottom-to-top line ordering and that sparse symbolic material stays gua-only instead of pretending to cover every line.

slot_count = 64 gua + (64 * 6 lines) + 2 use slots
         = 450 structured retrieval positions

reading_context = cast method + timestamp + changing lines
              + hexagram payload + Najia + BaZi
              + deterministic source excerpts
              + bounded AI controls

Product behavior

A user can create a reading, select a method, enter a question, choose the current time or a supplied timestamp, optionally enable AI, and then review the result through summary, hexagram sources, Najia structure, and AI follow-up.

Follow-up is tied to the same session. If the original OpenAI response id is available, the system continues from it. If not, it reconstructs the context from the stored payload snapshot. That makes the chat thread a continuation of the reading instead of a disconnected second prompt.

1. cast or enter lines
2. resolve hexagram and moving lines
3. assemble deterministic sources
4. generate controlled AI analysis
5. persist session and follow-up chat

Product control surface

The product already has the shape of an operating system for reflective decisions. The backend schema stores session identity, selected models, follow-up model, chat turns, token usage, summary text, payload snapshots, and chat-message rows. Those fields are enough to measure activation, follow-up conversion, session reopen behavior, deletion behavior, and token economics without changing the core product.

What this shows

The project is about provenance, continuity, and controls. The model stays separate from the database. The app has a data layer, a session layer, a product layer, and explicit operating limits.

That makes it a defensible prototype for bilingual reflective software: classical sources remain attached to the generated analysis, model output is bounded by structured context, and repeated use creates persistent session history.