I Ching

An offline-first, private Android app for casting, exploring, and journaling I Ching (Book of Changes) divination readings. Built with Jetpack Compose and a dark ink-wash aesthetic.

• Completely offline — no internet permission, no account, no ads, no tracking. Everything stays on your device.
• James Legge (1882) translation included — the first academic English translation, in the public domain.
• Bring your own translation — the app dynamically discovers translation sources at runtime; drop in your own *_iching.json and it appears in Settings with no code changes. See Adding Your Own Translation below.
• Full reference library — browse all 64 hexagrams, filter by trigram, and explore hexagram relationships.
• Private journal — save readings with your own questions and notes, with local zip backup/restore.

---

Screenshots

0. Splash Screen	1. Start Screen	2. Cast Screen
3. Reading Screen	4. Reading (Changing Lines)	5. Related Gua
6. Save to Journal	7. Journal	8. Hexagram Library
9. Hexagram Library (Filter)	10. Settings	11. Share Options

---

Requirements

• An Android phone running Android 8.0 (Oreo) or newer (API level 26+).
• ~30 MB of free storage.

The app is not on the Google Play Store, so it is installed by building it from source.

---

Installing on your Android phone

You'll need Android Studio (or the Android SDK command-line tools) and JDK 17.

Note

If building strictly from the command line, make sure you have the ANDROID_HOME environment variable configured, or open the project in Android Studio once first to automatically generate the local.properties file.

1. Clone the repository and open it in Android Studio, or use the command line from the project root.
2. Build the debug APK:

   ./gradlew assembleDebug        # macOS/Linux
   .\gradlew.bat assembleDebug    # Windows

   The APK is written to app/build/outputs/apk/debug/app-debug.apk.
3. Install directly to a connected phone (USB debugging enabled) with either:
   • Android Studio: press Run ▶ with your phone selected, or
   • the command line:

     adb install -r app/build/outputs/apk/debug/app-debug.apk

---

How to use the app

The app opens on the Cast screen. Three tabs run along the bottom — Cast, Journal, Library — and a gear icon opens Settings.

On first launch the app builds its local hexagram database from whatever translation source(s) it finds in assets/; this happens automatically and only once.

1. Cast a reading

1. On the Cast tab, optionally type your question or focus in the text field.
2. Cast the six lines of the hexagram (bottom to top). How you cast depends on your chosen Divination Method (see Settings):
   • Auto Toss — the coins are thrown for you in sequence.
   • Manual Toss — tap the toss button once for each of the six lines.
   • Shake — physically shake your phone to throw the coins.
3. Each cast produces one line; changing (moving) lines are marked. Once all six lines are set, tap Read Oracle.

2. Read the oracle

The reading screen shows your Primary Hexagram — its Chinese character, name, and metadata badges (element, "recite as" mnemonic, lunar month, Yin/Yang balance). Content is organised into tabs and sections:

• Primary Gua — the Decision (Judgment) and its commentary, the Symbol (Great Image), the Yao (line) texts, the character etymology (Name & Structure), and Historical Significance. For Hexagrams 1 and 2 an extra Wen Yen (Confucius's Commentary) section appears.
• Changing Lines — only the active moving lines and their guidance. Tap a changing line to jump to a preview of the hexagram that line transforms into.
• Relating Gua — the transformed hexagram, shown when your cast has changing lines.

You can also explore hexagram relationships (Opposite, Inverse, Mutual/Nuclear) and tap a trigram to see every hexagram that contains it.

From this screen you can:

• ⭐ Save to Journal — stores the reading with your question; the star turns gold once saved.
• Share — send the reading as plain text to any other app.

3. Journal

The Journal tab lists your saved readings in reverse-chronological order. For each entry you can:

• Tap it to re-open the full reading.
• ✏️ Edit to add or change a personal note.
• 🗑️ Delete the entry (with confirmation).

Backup & restore (in the Journal screen): export your whole journal to a .zip file anywhere you choose, and import it back later. Restore is conservative — it never overwrites entries you've edited locally, and reports how many entries were restored vs. skipped. (See Journal Backup & Restore Semantics below.)

4. Library

The Library tab is a reference browser for all 64 hexagrams. Scroll the full list or filter by upper/lower trigram, and tap any hexagram to read its complete entry — the same rich content as a live reading, minus the changing lines.

5. Settings

Open Settings (gear icon) to configure:

• App Theme — Dark Ink (default), Warm Rice Paper (light), or System Default.
• Translation Text Source — lists whatever translation(s) are installed (James Legge by default). Switching re-renders every reading and library entry in that translation. If you've added your own translation file, it appears here automatically.
• Divination Method — Auto Toss, Manual Toss, or Shake device.
• Interpretation Method — Manual (show all changing lines, you interpret), Master Yin (rule-based single line), or Nanjing Algorithm (mathematical single line).
• Coin Visual Style — Minimalist Calligraphy or Traditional Bronze.
• Haptic Feedback — vibrate on coin tosses.

---

Privacy

• No internet permission is declared — the app cannot send your questions, readings, or notes anywhere.
• All data lives in a local database on your device.
• Journal database files are excluded from Android's automatic cloud backup (via data_extraction_rules.xml); the only way your journal leaves the device is the manual zip export you trigger yourself.

---

For developers

Tech stack

• UI / Presentation: Jetpack Compose, Navigation Compose, Material 3
• Dependency Injection: Dagger Hilt
• Local Database: Room (schema version 4; unencrypted at rest — encryption can be added via SQLCipher if required)
• Preferences: DataStore Preferences
• Build: Gradle Kotlin DSL + version catalog, Kotlin 2.4, compileSdk/targetSdk 37, minSdk 26

Build & test commands

.\gradlew.bat assembleDebug              # build the debug APK
.\gradlew.bat testDebugUnitTest          # JVM unit tests
.\gradlew.bat connectedDebugAndroidTest  # instrumented E2E UI tests (needs a device)

Note: connectedDebugAndroidTest clears the local debug database for deterministic results. Don't run it on a build whose journal entries you want to keep.

Data translation sources

• James Legge (1882) — the only translation bundled in this repository (app/src/main/assets/legge_iching.json), complete 64/64 coverage. It's the first academic English translation and is in the public domain, so it can ship in an open-source repo without licensing concerns.
• Translation sources are discovered dynamically at runtime, not hardcoded — see below.

Adding Your Own Translation

Translation sources are not a fixed list in the code. On startup, DatabaseSeeder scans app/src/main/assets/ for every file whose name ends in _iching.json and seeds each one it finds. Whatever it seeds is what shows up in Settings → Translation Text Source — there is nothing else to wire up.

To add a translation:

1. Use schema_template.json as your structural reference. It documents every field the app reads, marked REQUIRED or optional, matching the app's Room entities exactly.
2. Fastest, safest starting point: copy app/src/main/assets/legge_iching.json to app/src/main/assets/<yourkey>_iching.json and only replace the text fields (names, decision/symbol text, line titles/oracle text, and any of the optional narrative fields you want to fill in). Leave the structural fields — id, upperTrigramId, lowerTrigramId, hostLineNumber, oppositeHexagramId, mutualHexagramId, lineNumber, lineType, alternatesToHexagramId — exactly as they are. These encode the King Wen sequence and each hexagram's Yin/Yang line pattern, which are identical across every real translation; getting them wrong won't crash the app, but will silently mislabel a hexagram or point a changing line at the wrong target.
3. Naming becomes the display name. <yourkey>_iching.json is turned into a key (<YOURKEY>, uppercased) and then a display name — my_translation_iching.json becomes "My Translation" in Settings. LEGGE has a curated display name/description built in; any other key gets this derived Title Case name automatically.
4. Rebuild the app. A fresh install always seeds everything it finds. If you're updating an already-installed app instead of doing a fresh install, bump CURRENT_ASSET_VERSION in IChingApplication.kt (or uninstall/reinstall, or clear the app's storage) — the seeder only re-scans assets/ when that version number increases.
5. That's it. No enum, no ViewModel, no Settings UI code to touch — your new source appears in the picker and every screen that reads hexagram data (Cast, Reading, Journal, Library) uses it once selected.

If your saved translation-source preference is ever missing (e.g. you removed a source's JSON file), the app falls back to Legge if present, otherwise the first available source alphabetically — it never crashes on a missing source.

Journal backup & restore semantics

The Journal supports manual zip backup/export and restore/import via SAF (Storage Access Framework). Restore behavior is deliberately conservative:

• Imported entries carry their original database ID. On restore, the import uses an ignore-on-conflict strategy: any imported entry whose ID already exists locally is skipped, never overwritten. This protects newer local edits from being clobbered by an older backup.
• The restore message reports the true outcome: Restored X of Y entries (Z skipped as already present).
• This is intended for same-device restores or a reset/reinstall of the same device. Because matching is by exact ID, cross-device merges are not supported: if two devices independently created entries that happen to share IDs (IDs are sequential per device), restoring one device's backup onto the other will silently skip the colliding IDs rather than merge them. Treat backup/restore as a whole-journal snapshot for one device, not a multi-device sync mechanism.